diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..600d2d33badf45cc068e01d2e3c837e11c417bc4 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.vscode \ No newline at end of file diff --git a/md/.gitkeep b/md/.gitkeep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/md/annex-a.md b/md/annex-a.md new file mode 100644 index 0000000000000000000000000000000000000000..8bda05c5b408b6fd4d50379cfa194edcce27813d --- /dev/null +++ b/md/annex-a.md @@ -0,0 +1,1067 @@ +# Annex A [(informative)]{.inform}: Examples of using the HTTP binding of the API + +## A.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.6]. + +## A.2 Create Entity of Type Vehicle + +### A.2.1 Introduction + + + +>>> [!tip] EXAMPLE: + +This example illustrates how to create a new Entity of type +["Vehicle"]{.HTML-Code}. + +>>> + + + +### A.2.2 HTTP request + +**POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} + +Content-Type: application/ld+json + +Content-Length: 927 + +```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"] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +### A.2.3 HTTP response + +201 Created + +Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567 + +## A.3 Query Entities + +### A.3.1 Introduction + + + +>>> [!tip] 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. + +>>> + + + +### A.3.2 HTTP request + +**GET** +[/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} + +Accept: application/ld+json + +Link: +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.3.3 HTTP response + +200 OK + +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" + ] + } +] +``` + +## A.4 Query Entities (pagination) + +### A.4.1 Introduction + + + +>>> [!tip] 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. + +>>> + + + +### A.4.2 HTTP request + +**GET** +[/ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.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" + +```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" + ] + } +] +``` + +## A.5 Temporal Query + +### A.5.1 Introduction + + + +>>> [!tip] 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 1st of August +at noon and the 1st of August at 01 PM. + +>>> + + + + + +>>> [!tip] 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 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. + +>>> + + + +### A.5.2 HTTP request #1 + +**GET** +[/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.5.3 HTTP response #1 + +200 OK + +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" + ] + } +] +``` + +### A.5.4 HTTP request #2 + +**GET** +[/ngsild/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]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.5.5 HTTP response #2 + +200 OK + +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" + ] + } +] +``` + +## A.6 Temporal Query (simplified representation) + +### A.6.1 Introduction + + + +>>> [!tip] 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 1st of August +at noon and the 1st of August at 01 PM. Simplified representation is +required. + +>>> + + + +### A.6.2 HTTP request + +**GET** +[/ngsild/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**]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.6.3 HTTP response + +200 OK + +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" + ] + } +] +``` + +## A.7 Retrieve available Entity Types + +### A.7.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back all entity types for which entity instances are currently available in +the NGSI-LD system. + +>>> + + + +### A.7.2 HTTP request + +**GET** [/ngsi-ld/v1/types]{.HTML-Variable} + +Accept: application/json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.7.3 HTTP response + +200 OK + +Content-Type: application/json + +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" + ] +} +``` + + + + +>>> [!note] NOTE: + +All entity types that can be found in the provided _`@context`_ +are given as short names, the others as Fully Qualified Names (FQNs). + +>>> + + + +## A.8 Retrieve details of available Entity Types + +### A.8.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back the details of all entity types for which entity instances are +currently available in the NGSI-LD system. + +>>> + + + +### A.8.2 HTTP request + +**GET** [/ngsi-ld/v1/types?details=true]{.HTML-Variable} + +Accept: application/json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.8.3 HTTP response + +200 OK + +Content-Type: application/json + +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"] + } +] +``` + + + +>>> [!note] 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. + +>>> + + + +## A.9 Retrieve available Entity Type information + +### A.9.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back the details of entity type ["Vehicle"]{.HTML-Code} (for which entity +instances are currently available in the NGSI-LD system). + +>>> + + + +### A.9.2 HTTP request + +**GET** [/ngsi-ld/v1/types/Vehicle]{.HTML-Variable} + +[Alternative with FQN: **GET** +[/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle]{.HTML-Variable} + +Accept: application/json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.9.3 HTTP response + +200 OK + +Content-Type: application/json + +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"] + } + ] +} +``` + +## A.10 Retrieve available Attributes + +### A.10.1 Introduction + + + +>>> [!tip] 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. + +>>> + + + +### A.10.2 HTTP request + +**GET** [/ngsi-ld/v1/attributes]{.HTML-Variable} + +Accept: application/json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.10.3 HTTP response + +200 OK + +Content-Type: application/json + +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" + ] +} +``` + + + +>>> [!note] NOTE: + +The attribute names that can be found in the provided +_`@context`_ are given as short names, the others as fully +qualified names (FQNs). + +>>> + + + +## A.11 Retrieve details of available Attributes + +### A.11.1 Introduction + + + +>>> [!tip] 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. + +>>> + + + +### A.11.2 HTTP request + +**GET** [/ngsi-ld/v1/attributes?details=true]{.HTML-Variable} + +Accept: application/json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.11.3 HTTP response + +200 OK + +Content-Type: application/json + +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"] + } +] +``` + + + +>>> [!note] 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. + +>>> + + + +## A.12 Retrieve available Attribute information + +### A.12.1 Introduction + + + +>>> [!tip] 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). + +>>> + + + +### A.12.2 HTTP request + +**GET** [/ngsi-ld/v1/attributes/brandName]{.HTML-Variable} + +\[ Alternative with FQN: **GET** +[/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName]{.HTML-Variable} +\] + +Accept: application/json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.12.3 HTTP response + +200 OK + +Content-Type: application/json + +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 +} +``` + +## A.13 Query Entities (natural language filtering) + +### A.13.1 Introduction + + + +>>> [!tip] 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. + +>>> + + + +### A.13.2 HTTP request + +**GET** +[/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]=="Vauxhall +Viva"&format=**simplified**&lang=de]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.13.3 HTTP response + +200 OK + +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" + ] + } +] +``` + +## A.14 Temporal Query (aggregated representation) + +### A.14.1 Introduction + + + +>>> [!tip] 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 1st of August at noon and the +1st of August at 01 PM, aggregated by periods of 4 minutes. + +>>> + + + +### A.14.2 HTTP request + +**GET** +[/ngsild/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**]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.14.3 HTTP response + +200 OK + +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" + ] + } +] +``` + +## A.15 Scope Queries + +### A.15.1 Introduction + + + +>>> [!tip] 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}. + +>>> + + + +### A.15.2 HTTP request + +**GET** +[/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.15.3 HTTP response + +200 OK + +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" + ] + } +] +``` + +## A.16 Temporal Scope Queries + +### A.16.1 Introduction + + + +>>> [!tip] 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 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. + +>>> + + + +### A.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"]{.HTML-Variable} + +Accept: application/ld+json + +Link: ; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +### A.16.3 HTTP response + +200 OK + +Content-Type: application/ld+json + +```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" + ] + } +] +``` + +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. diff --git a/md/annex-b.md b/md/annex-b.md new file mode 100644 index 0000000000000000000000000000000000000000..8766159ab5abb7266178b8ae670e65e6e8356bf8 --- /dev/null +++ b/md/annex-b.md @@ -0,0 +1,107 @@ +# Annex B [(informative)]{.inform}: Conventions and syntax guidelines + +When new terms are defined, they are marked in bold, and terms are capitalized +thereafter. + + + +>>> [!tip] EXAMPLE 1: + +**NGSI-LD Linked Entity**, [Linked Entity]{.HTML-Keyboard}. + +>>> + + + +API Parameter names are always in lowercase. + + + +>>> [!tip] EXAMPLE 2: + +_`options`_. + +>>> + + + +Entity Types are defined using lowercase but with a starting capital letter. + + + +>>> [!tip] EXAMPLE 3: + +Vehicle, Building, ParkingSpace. + +>>> + + + +JSON-LD nodes and terms are always defined using camel case notation starting +with lower case. + + + +>>> [!tip] 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. + + + +>>> [!tip] EXAMPLE 5: + +_ListRelationship_, _GeoProperty_, _Geometry_, _Second_, _Number_. + +>>> + + + +When referring to literal strings double quotes are used. + + + +>>> [!tip] 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. + + + +>>> [!tip] 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. + + + +>>> [!tip] 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/md/annex-bibliography.md b/md/annex-bibliography.md new file mode 100644 index 0000000000000000000000000000000000000000..89d4623ed5e7cd2c080d2165c511c2886d752925 --- /dev/null +++ b/md/annex-bibliography.md @@ -0,0 +1,4 @@ +# Annex [(informative)]{.inform}: Bibliography + +- + diff --git a/md/annex-change_history.md b/md/annex-change_history.md new file mode 100644 index 0000000000000000000000000000000000000000..7e1bbe289cf4227b6f844c896871628f98e78ab6 --- /dev/null +++ b/md/annex-change_history.md @@ -0,0 +1,12 @@ +# Annex [(informative)]{.inform} Change history + +::: TAL ++-----------------------+-----------------------+------------------------------------------+ +| Date | Version | Information about changes | ++=======================+=======================+==========================================+ +| | {TAC} | | +| | | | +| | <#> | | ++-----------------------+-----------------------+------------------------------------------+ +::: + diff --git a/md/clause-10.md b/md/clause-10.md new file mode 100644 index 0000000000000000000000000000000000000000..db0bba5253245408d30df3338654659ee82ca34f --- /dev/null +++ b/md/clause-10.md @@ -0,0 +1,328 @@ +# 10 Storing, Managing and Serving \@contexts Resources + +## 10.1 Introduction + +Clause+++root defines the resources related to the management of JSON-LD +_`@contexts`_ in an NGSI-LD system. An NGSI-LD system may store _`@contexts`_ in +its internal _`@context`_ storage, and it may serve them to clients. The +resources defined in this clause allow clients to list, add, delete, and +retrieve _`@contexts`_. + +## 10.2 Resource: jsonldContexts/ + +### 10.2.1 Description + +This resource represents the _`@contexts`_ known to an NGSI-LD system. + +### 10.2.2 Resource definition + +Resource URI: + +- _`/jsonldContexts/`_ + +### 10.2.3 Resource methods + +#### 10.2.3.1 GET/HEAD + +This method is associated to the operation "List _`@contexts`_" and shall +exhibit the behaviour defined by [n.1] ~clause 13.3, and it provides information +about stored _`@contexts`_ as part of the HTTP response payload body. +Figure+++below shows the List _`@contexts`_ interaction. + + + +::: FL + +::: + +::: TF +Figure: List \@contexts interaction +::: + + + +The request parameters that shall be supported by implementations are those +defined in Table+++below and Table+++below+++below describes the request body +and possible responses. + + + +::: TH +Table: 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}. | ++-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: List \@contexts request body and possible responses +::: + +::: TAL + ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 by [n.1] clause ~13.3.5, representing metadata about stored | +| | | | | _`@contexts`_. | +| | or | | | | +| | | | | | +| | JSON Object[] | | | | +| +---------------------------------------------+-------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +::: + + + +#### 10.2.3.2 POST + +This method is bound to the operation "Add _`@context`_" and shall exhibit the +behaviour defined by [n.1] ~clause 13.2, taking the _`@context`_ to be added +from the HTTP request payload body. Figure+++below shows the Add _`@context`_ +interaction and Table+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Add \@context interaction +::: + + + + + +::: TH +Table: Add \@context request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 10.3 Resource: jsonldContexts/{contextId} + +### 10.3.1 Description + +This resource represents a JSON-LD _`@context`_ stored in the broker's internal +_`@context`_ storage. + +### 10.3.2 Resource definition + +Resource URI: + +- _`/jsonldContexts/{contextId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: 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. | ++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +### 10.3.3 Resource methods + +#### 10.3.3.1 GET/HEAD + +This method is associated to the operation "Serve _`@context`_" and shall +exhibit the behaviour defined by [n.1] ~clause 13.4. The _`@context`_ identifier +is the value of the resource URI variable "contextId". Figure+++below shows the +HTTP Serve _`@context`_ interaction. + + + +::: FL + +::: + +::: TF +Figure: Serve \@context interaction +::: + + + +The request parameters that shall be supported by implementations are those +defined in Table+++below and Table+++below+++below describes the request body +and possible responses. + + + +::: TH +Table: 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. | ++-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Serve \@context request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 | +| +---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | | | | 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 [n.1] ~clause 13.4.5, which metadata of a JSON-LD "local context". | +| +---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | | | | It is used to indicate that the request or its content is incorrect, see clause 6.3.2. | +| | | | | | +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 1 | 422 Unprocessable | It is used when a client indicated an _`@context`_ of type ["Cached"]{.HTML-Code}, see clause 6.3.2. | ++---------------+---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 10.3.3.2 DELETE + +This method is associated to the operation "Delete and Reload _`@context`_" and +shall exhibit the behaviour defined by [n.1] ~clause 13.5. The Entity identifier +is the value of the resource URI variable "contextId". Figure+++below shows the +delete entity interaction. The request parameters that shall be supported are +those defined in Table+++below and Table+++below+++below describes the request +body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Delete and Reload \@context interaction +::: + + + + + +::: TH +Table: 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 [n.1] ~clause 13.5.4. | ++-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Delete and Reload \@context request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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 [n.24]) | 1 | 504 Gateway Timeout | It is used when re-downloading fails. | ++---------------+---------------------------------------------+-------------+---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + diff --git a/md/clause-11.md b/md/clause-11.md new file mode 100644 index 0000000000000000000000000000000000000000..deaa1e5df0e0b99485ae1ecc36731210e7ba11b8 --- /dev/null +++ b/md/clause-11.md @@ -0,0 +1,437 @@ +# 11 Context Source Entity mapping resources + +## 11.1 Introduction + +Clause+++root defines the resources related to creating and managing Entity +Maps. + +## 11.2 Resource: entityMaps/ + +### 11.2.1 Description + +This resource represents the Entity maps in an NGSI-LD system. + +### 11.2.2 Resource definition + +Resource URI: + +- _`/entityMaps/`_ + +### 11.2.3 Resource methods + +#### 11.2.3.1 GET/HEAD + +This method is associated to the operation "Create EntityMap for Query Entities" +and shall exhibit the behaviour defined by [n.1] ~clause 14.5, 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+++root.2.3.2. Figure+++below shows the Create +EntityMap for Query Entities interaction. + + + +::: FL + +::: + +::: TF +Figure 11.2.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 7.2.3.1-1. Table+++below +describes the request body and possible responses. + + + +::: TH +Table 11.2.3.1-1: Create EntityMap for Query Entities request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| Request Body | Data Type | Cardinality | Remarks | ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | {TAL} | {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"]{.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 9.5.3. | +| | | | | | +| | | | | The response shall also include a ["Preference-Applied"]{.HTML-Code} HTTP header set to ["ngsi-ld="]{.HTML-Code}. | +| +---------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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+++clause-6+++root.4.2. | ++---------------+---------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + +#### 11.2.3.2 POST + +This method is associated to the operation "Create EntityMap for Query Entities" +and shall exhibit the behaviour defined by [n.1] ~clause 14.5. Figure+++below +shows the operation interaction and Table+++below describes the request body and +possible responses. + + + +::: FL + +::: + +::: TF +Figure 11.2.3.2-1: Create EntityMap for Query Entities via POST interaction +::: + + + + + +::: TH +Table 11.2.3.2-1: Create EntityMap for Query Entities via POST request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + +## 11.3 Resource: temporal/entityMaps + +### 11.3.1 Description + +This resource is used for creating entityMaps based on temporal queries in an +NGSI-LD system. + +### 11.3.2 Resource definition + +Resource URI: + +- _`/temporal/entityMaps/`_ + +### 11.3.3 Resource methods + +#### 11.3.3.1 GET/HEAD + +This method is associated to the operation "Create EntityMap for Query Temporal +Evolution of Entities" and shall exhibit the behaviour defined by [n.1] ~clause +14.6, 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+++root.3.3.2. +Figure+++below shows this interaction. + + + +::: FL + +::: + +::: TF +Figure 11.3.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 +8.2.3.1-1. Table+++below describes the request body and possible responses. + + + +::: TH +Table 11.3.3.1-1: Create EntityMap for Query Temporal Evolution of Entities request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + +#### 11.3.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 [n.1] ~clause +14.6. Figure+++below shows the operation interaction and Table+++below describes +the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure 11.3.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST interaction +::: + + + + + +::: TH +Table 11.3.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + +## 11.4 Resource: entityMaps/{entityMapId} + +### 11.4.1 Description + +This resource represents an EntityMap available in an NGSI-LD system's internal +storage or memory. + +### 11.4.2 Resource definition + +Resource URI: + +- _`/entityMaps/{entityMapId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table 11.4.2-1: URI variables +::: + +::: TAL ++-----------------------------------+----------------------------------------------------------------+ +| Name | Definition | ++===================================+================================================================+ +| entityMapId | Id (URI) of the EntityMap to be retrieved, updated or deleted. | ++-----------------------------------+----------------------------------------------------------------+ +::: + + +### 11.4.3 Resource methods + +#### 11.4.3.1 GET/HEAD + +This method is associated to the operation "Retrieve EntityMap" and shall +exhibit the behaviour defined by [n.1] ~clause 14.2. The EntityMap identifier is +the value of the resource URI variable "entityMapId". Figure+++below shows the +Retrieve EntityMap interaction and Table+++below describes the request body and +possible responses. + + + +::: FL + +::: + +::: TF +Figure 11.4.3.1-1: Retrieve EntityMap +::: + + + + + +::: TH +Table 11.4.3.1-1: Retrieve EntityMap request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 | 200 OK | A response body containing the JSON-LD representation of the target entity. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see Clause+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + +#### 11.4.3.2 PATCH + +This method is associated to the operation "Update EntityMap" and shall exhibit +the behaviour defined by [n.1] ~clause 14.3. The EntityMap identifier is the +value of the resource URI variable "entityMapId". Figure+++below shows the +Update EntityMap interaction and Table+++below describes the request body and +possible responses. + + + +::: FL + +::: + +::: TF +Figure 11.4.3.2-1: Update EntityMap +::: + + + + + +::: TH +Table 11.4.3.2-1: Update EntityMap request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see Clause+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + +#### 11.4.3.3 DELETE + +This method is associated to the operation "Delete EntityMap" and shall exhibit +the behaviour defined by [n.1] ~clause 14.4. The Entity identifier is the value +of the resource URI variable "contextId". Figure+++below shows the delete entity +interaction and Table+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure 11.4.3.3-1: Delete and Reload \@context interaction +::: + + + + + +::: TH +Table 11.4.3.3-1: Delete EntityMap request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an _`@context`_ identifier not known to the system, see Clause+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + diff --git a/md/clause-12.md b/md/clause-12.md new file mode 100644 index 0000000000000000000000000000000000000000..a0353e69697d3210c722f05844b9d3e0bf34b557 --- /dev/null +++ b/md/clause-12.md @@ -0,0 +1,69 @@ +# 12 Context Source identity information resources + +## 12.1 Introduction + +This clause defines the resources used to expose identity information about a +[Context Source]{.HTML-Keyboard}. + +## 12.2 Resource: info/sourceIdentity + +### 12.2.1 Description + +This resource represents identity information about the [Context +Source]{.HTML-Keyboard} itself. + +### 12.2.2 Resource definition + +Resource URI: + +- _`/info/sourceIdentity`_ + +### 12.2.3 Resource methods + +#### 12.2.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Context Source Identity +Information" and shall exhibit the behaviour defined by [n.1] ~clause 15.2. +Figure+++below shows the Retrieve Context Source Identity Information +interaction and Table+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Context Source Identity Information +::: + + + + + +::: TH +Table: Retrieve Context Source Identity Information request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 501 Not Implemented | It is used by [Context Sources]{.HTML-Keyboard} to indicate that retrieval of the Context Source information is unsupported | +| | | | | see [n.1] ~clause 15.2.4. | ++---------------+---------------------------------------------+-------------+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + diff --git a/md/clause-13.md b/md/clause-13.md new file mode 100644 index 0000000000000000000000000000000000000000..260456f85d75d8546359811892433abff6d84a4d --- /dev/null +++ b/md/clause-13.md @@ -0,0 +1,428 @@ +# 13 Snapshot functionality resources + +## 13.1 Introduction + +Clause+++root defines the resources related to creating and managing Snapshots. + +## 13.2 Resource: snapshots/ + +### 13.2.1 Description + +This resource represents Snapshots available in an NGSI-LD system. + +### 13.2.2 Resource definition + +Resource URI: + +- _`/snapshots/`_ + +### 13.2.3 Resource methods + +#### 13.2.3.1 POST + +This method is associated to the operation "Create Snapshot" and shall exhibit +the behaviour defined by [n.1] ~clause 16.2. Figure+++below shows the operation +interaction and Table+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure 13.2.3.1-1: Create Snapshot interaction +::: + + + + + +::: TH +Table 13.2.3.1-1: Create Snapshot request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 409 Conflict | It is used to indicate that a Snapshot having the Snapshot identifier included in the request body already exists, see Clause+++clause-6++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 13.2.3.2 DELETE + +This method is associated to the operation "Purge Snapshots" and shall exhibit +the behaviour defined by [n.1] ~clause 16.7. Figure+++below shows the Purge +Snapshot interaction. + + + +::: FL + +::: + +::: TF +Figure 13.2.3.2-1: Purge Snapshots interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in Table+++below and Table 13.2.3.2-2 describes the request body and possible +responses. + + + +::: TH +Table 13.2.3.2-1: Purge Snapshots URL parameters +::: + + + ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+=====================================================================================+ +| q | String | 1 | Query as per [n.1] ~clause 7.2.3, restricted to members of the Snapshot data type. | ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------+ + + + + +::: TH +Table 13.2.3.2-2: Purge Snapshots request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided a filter not matching any Snapshots, see Clause+++clause-6++root.3.2. | ++---------------+---------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 13.3 Resource: snapshots/{snapshotId} + +### 13.3.1 Description + +This resource represents a snapshot in an NGSI-LD system. + +### 13.3.2 Resource definition + +esource URI: + +- _`/snapshots/{snapshotId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table 13.3.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. | ++-----------------------------------+-----------------------------------------------------------------------------------------------------+ +::: + + + +### 13.3.3 Resource methods + +#### 13.3.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Snapshot Status" and shall +exhibit the behaviour defined by [n.1] ~clause 16.4. The Snapshot identifier is +the value of the resource URI variable "snapshotId". Figure+++below shows the +Retrieve Snapshot Status interaction and Table+++below describes the request +body and possible responses. + + + +::: FL + +::: + +::: TF +Figure 13.3.3.1-1: Retrieve Snapshot Status interaction +::: + + + + + +::: TH +Table 13.3.3.1-1: Retrieve Snapshot Status request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | Snapshot | 1 | 200 OK | A response body containing the JSON-LD representation of the target Snapshot status. | +| | | | | | +| | | | | | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see Clause+++clause-6++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 13.3.3.2 PATCH + +This method is associated to the operation "Update Snapshot Status" and shall +exhibit the behaviour defined by [n.1] ~clause 16.5. The Snapshot identifier is +the value of the resource URI variable "snapshotId". Figure+++below shows the +Update Snapshot Status interaction and Table+++below describes the request body +and possible responses. + + + +::: FL + +::: + +::: TF +Figure 13.3.3.2-1: Update Snapshot Status interaction +::: + + + + + +::: TH +Table 13.3.3.2-1: Update Snapshot Status request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see Clause+++clause-6++root.3.2. | ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 13.3.3.3 DELETE + +This method is associated to the operation "Delete Snapshot" and shall exhibit +the behaviour defined by [n.1] ~clause 16.6. The Snapshot identifier is the +value of the resource URI variable "snapshotId". Figure+++below shows the Delete +Snapshot interaction and Table+++below describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure 13.3.3.3-1: Delete Snapshot interaction +::: + + + + + +::: TH +Table 13.3.3.3-1: Delete Snapshot request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided a snapshot identifier not known to the system, see Clause+++clause-6++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 13.4 Resource: snapshots/{snapshotId}/clone + +### 13.4.1 Description + +This resource enables the cloning of a snapshot in an NGSI-LD system. + +### 13.4.2 Resource definition + +Resource URI: + +- _`/snapshots/{snapshotId}/clone`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table 13.4.2-1: URI variables +::: + + +::: TAL ++-----------------------------------+----------------------------------------------------+ +| Name | Definition | ++===================================+====================================================+ +| snapshotId | Id (URI) of the Snapshot to be queried or deleted. | ++-----------------------------------+----------------------------------------------------+ +::: + + + +### 13.4.3 Resource methods + +#### 13.4.3.1 POST + +This method is associated to the operation "Clone Snapshot" and shall exhibit +the behaviour defined by [n.1] ~clause 16.3. The Snapshot identifier is the +value of the resource URI variable "snapshotId". Figure+++below shows the Clone +Snapshot interaction and Table+++below describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure 13.4.3.1-1: Clone Snapshot interaction +::: + + + + + +::: TH +Table 13.4.3.1-1: Clone Snapshot request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 1 | 409 Conflict | It is used to indicate that the Snapshot having the Snapshot identifier included in the request body already exists, see Clause+++clause-6++root.3.2.| +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + diff --git a/md/clause-1_Scope.md b/md/clause-1_Scope.md new file mode 100644 index 0000000000000000000000000000000000000000..c08ffa9bacd1e8e8b49f520802a941b56e2a4a9e --- /dev/null +++ b/md/clause-1_Scope.md @@ -0,0 +1,5 @@ +# 1 Scope + +The present document defines the HTTP binding for the NGSI-LD API specified in +[n.1]. It supersedes prior versions, including ETSI GS CIM 009 [i.1] and ETSI GS +CIM 004 [i.2]. diff --git a/md/clause-2_References.md b/md/clause-2_References.md new file mode 100644 index 0000000000000000000000000000000000000000..d21d63d54e96aa1be3ee2ee831e680a827db6a4c --- /dev/null +++ b/md/clause-2_References.md @@ -0,0 +1,118 @@ +# 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](https://docbox.etsi.org/Reference/). + + + +>>> [!note] 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. + + + +::: REFS +[n.1] ETSI TS 104 175: "Data Solutions (DATA); NGSI-LD API Specification". + +[n.2] [IETF RFC 3987](https://www.rfc-editor.org/info/rfc3987): "Internationalized Resource Identifiers (IRIs)". + +[n.3] The Unicode Consortium: "[Unicode® 15.0.0](https://www.unicode.org/versions/Unicode15.0.0/)". + +[n.4] [IETF RFC 8259](https://www.rfc-editor.org/info/rfc8259): "The JavaScript Object Notation (JSON) Data Interchange Format". + +[n.5] [IETF RFC 9110](https://www.rfc-editor.org/info/rfc9110): "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content". + +[n.6] [IETF RFC 7232](https://www.rfc-editor.org/info/rfc7232): "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests". + +[n.7] [IETF RFC 2818](https://www.rfc-editor.org/info/rfc2818): "HTTP Over TLS". + +[n.8] [IETF RFC 5246](https://www.rfc-editor.org/info/rfc5246): "The Transport Layer Security (TLS) Protocol Version 1.2". + +[n.9] [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". + +[n.10] [IETF RFC 7396](https://www.rfc-editor.org/info/rfc7396): "JSON Merge Patch". + +[n.11] W3C® Recommendation 16 July 2020: "[JSON-LD 1.1 - A JSON-based Serialization for Linked Data](http://www.w3.org/TR/json-ld/)". + +[n.12] [IETF RFC 7240](https://www.rfc-editor.org/info/rfc7240): "Prefer Header for HTTP". + +[n.13] [IETF RFC 8288](https://www.rfc-editor.org/info/rfc8288): "Web Linking". + +[n.14] [IETF RFC 7234](https://www.rfc-editor.org/info/rfc7234): "Hypertext Transfer Protocol (HTTP/1.1): Caching". + +[n.15] IANA: "[Hypertext Transfer Protocol (HTTP) Warn Codes](https://www.iana.org/assignments/http-warn-codes/http-warn-codes.xhtml)". + +[n.16] [IANA Registry of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). + +[n.17] [IETF RFC 7233](https://www.rfc-editor.org/info/rfc7233): "Hypertext Transfer Protocol (HTTP/1.1): Range Requests". + +[n.18] [IETF RFC 6906](https://www.rfc-editor.org/info/rfc6906): "The 'profile' Link Relation Type". + +[n.19] [IETF RFC 7230](https://www.rfc-editor.org/info/rfc7230): "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing". + +[n.20] [IETF RFC 6067](https://www.rfc-editor.org/info/rfc6067): "BCP 47 Extension U". + +[n.21] [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". + +[n.22] [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". + +[n.23] [IETF RFC 7946](https://www.rfc-editor.org/info/rfc7946): "The GeoJSON Format". + +[n.24] [IETF RFC 7807](https://www.rfc-editor.org/info/rfc7807): "Problem Details for HTTP APIs". +::: + + + +## 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] 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. + + + +::: REFS +[i.1] ETSI GS CIM 009: "Context Information Management (CIM); NGSI-LD API". + +[i.2] ETSI GS CIM 004 (V1.1.2): "Context Information Management (CIM); Application Programming Interface (API)". + +[i.3] [OpenAPI™ Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md). + +[i.4] [NGSI-LD OpenAPI™ Specification](https://forge.etsi.org/rep/cim/NGSI-LD/tree/master/spec). + +[i.5] [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.6] [ETSI GR CIM 008](https://www.etsi.org/deliver/etsi_gr/CIM/001_099/008/): "Context Information Management (CIM); NGSI-LD Primer". +::: + + diff --git a/md/clause-3_Definitions.md b/md/clause-3_Definitions.md new file mode 100644 index 0000000000000000000000000000000000000000..f70204f19199b07c3c9142e13fc7f53b2b0b8c92 --- /dev/null +++ b/md/clause-3_Definitions.md @@ -0,0 +1,547 @@ +# 3 Definition of terms, symbols and abbreviations + +## 3.1 Terms + +For the purposes of the present document, the following terms apply: + + + +>>> [!note] 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] 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 [n.2], +which extends the use of characters to Unicode characters [n.3] 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 + + + +>>> [!note] 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 + + + +>>> [!note] 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 + + + +>>> [!note] 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 + + + + + +>>> [!note] NOTE: + +In the NGSI-LD API, an NGSI-LD Entity Type is **uniquely identified by a URI**. + +>>> + + + + + +>>> [!tip] EXAMPLE 1: + +["Vehicle"]{.HTML-Code} is an NGSI-LD Entity Type and is identified with a proper URI. + +>>> + + + + + +>>> [!tip] 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} + +>>> + + + + + +>>> [!tip] 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 + + + +>>> [!note] NOTE: + +It can exist within another NGSI-LD system or within a non-NGSI-LD system. + +>>> + + + + + +>>> [!tip] 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 + + + +>>> [!tip] 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 + + + +>>> [!note] 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 + + + +>>> [!tip] EXAMPLE: + +"A bus route services the following bus stops" can be represented by an NGSI-LD +[ListRelationship]{.HTML-Definition} 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 + + + +>>> [!tip] 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 + + + +>>> [!tip] 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 URI , for instance +["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 + + + +>>> [!tip] 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}. + +>>> + + + + + +>>> [!tip] 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) + + + +>>> [!tip] 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 + + + +>>> [!tip] 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 + +Void. + +## 3.3 Abbreviations + +For the purposes of the present document, the following abbreviations apply: + + + +::: EW +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/md/clause-4.md b/md/clause-4.md new file mode 100644 index 0000000000000000000000000000000000000000..5c19854c26f1165e3005451f60b9c24eb5421675 --- /dev/null +++ b/md/clause-4.md @@ -0,0 +1,14 @@ +# 4 Introduction + +The present document defines the HTTP binding of the NGSI-LD API, whose abstract +operations are defined in [n.1]. In particular it defines the mapping of the +abstract operations of the NGSI-LD API to HTTP resources and verbs. Each HTTP +resource is defined [n.5][n.6], which verbs are applicable and what the related +request and response payload bodies are. + +In the present document, a number of rather obvious typographic conventions and +syntax guidelines are followed, and the reader is referred to Annex B for +details. + +A non-normative OpenAPI™ specification [i.3] of the referred HTTP binding can +be found in [i.4]. diff --git a/md/clause-5.md b/md/clause-5.md new file mode 100644 index 0000000000000000000000000000000000000000..997e2dd6e91a9dffb7250624af9adc42aaf7f7dc --- /dev/null +++ b/md/clause-5.md @@ -0,0 +1,442 @@ +# 5 Global definitions and resource structure + +All resource URIs of this API shall have the following root: + +- {apiRoot}/{apiName}/{apiVersion}/ + + + +>>> [!note] NOTE 1: + +The apiRoot discovery process is out of the scope of the present document. + +>>> + + + + + +>>> [!note] 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 [n.1] ~clause 4.3), whereas the Entity-related aspects would be +implemented by a [Context Broker]{.HTML-Keyboard}. + +>>> + + + + + +>>> [!note] 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 [n.7]). TLS version 1.2 as defined by IETF RFC 5246 +[n.8] 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+++below and methods defined +on them are shown in Table+++below. + +An OpenAPI companion specification is available, see [n.9]. + + + +::: FL + +::: + +::: TF +Figure: Resource URI structure of the NGSI-LD API +::: + + + + + +::: TH +Table: Resources and HTTP methods defined on them +::: + +::: TAC ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Resource Name | Resource URI | HTTP Method | Meaning | Clauses | ++===========================================================+===============================================================+=============+:========================================================================================================:+:=========================:+ +| Entity List | [/entities/]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Query entities | 10.4.3*; | +| | | | | 7.2.3.1 | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | {TAL} | {TAL} | +| | | | | | +| | | | Entity creation | 10.2.2*; | +| | | | | 7.2.3.2 | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | {TAL} | {TAL} | +| | | | | | +| | | | Purge entities | 10.2.12*; | +| | | | | 7.2.3.3 | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity by id | [/entities/**{entityId}**]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Entity retrieval by id | 10.4.2*; | +| | | | | 7.3.3.1 | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PATCH | {TAL} | {TAL} | +| | | | | | +| | | | Entity merge by id | 10.2.9*; 7.3.3.2 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PUT | {TAL} | {TAL} | +| | | | | | +| | | | Entity replacement by id | 10.2.10*; 7.3.3.3 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | {TAL} | {TAL} | +| | | | | | +| | | | Entity deletion by id | 10.2.8*; 7.3.3.4 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Attribute List | [/entities/**{entityId}**/attrs/]{.HTML-Variable} | POST | {TAL} | {TAL} | +| | | | | | +| | | | Append Attributes to Entity | 10.2.4*; 7.4.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PATCH | {TAL} | {TAL} | +| | | | | | +| | | | Update Attributes of an Entity | 10.2.3*; 7.4.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Attribute by id | [/entities/**{entityId}**/attrs/**{attrId}**]{.HTML-Variable} | PATCH | {TAL} | {TAL} | +| | | | | | +| | | | Partial Attribute update | 10.2.5*; 7.5.3.2 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PUT | {TAL} | {TAL} | +| | | | | | +| | | | Attribute replacement | 10.2.11*; 7.5.3.3 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | {TAL} | {TAL} | +| | | | | | +| | | | Attribute deletion | 10.2.7*; 7.5.3.4 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Subscriptions List | [/subscriptions/]{.HTML-Variable} | GET/HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Retrieve list of Subscriptions | 10.5.5*; 7.13.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | {TAL} | {TAL} | +| | | | | | +| | | | Create Subscription | 10.5.2*; 7.13.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Subscription by Id | [/subscriptions/**{subscriptionId}**]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Subscription retrieval by id | 10.5.4*; 7.14.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PATCH | {TAL} | {TAL} | +| | | | | | +| | | | Subscription update by id | 10.5.3*; 7.14.3.2 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | {TAL} | {TAL} | +| | | | | | +| | | | Subscription deletion by id | 10.5.6*; 7.14.3.3 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Types | [/types/]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Retrieve available entity types | 10.6.3* and 10.6.4*; | +| | | | | 7.15.3.1 | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Type | [/types/**{type}**]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Details about available entity type | 10.6.5*; 7.16.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Attributes | [/attributes/]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Available attributes | 10.6.6* and 10.6.7*; | +| | | | | 7.17.3.1 | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Attribute | [/attributes/**{attrId}**]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Details about available attribute | 10.6.8*; 7.18.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Context source registration list | [/csourceRegistrations/]{.HTML-Variable} | GET /HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Discover Csource registrations | 12.3.3*; 9.2.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | {TAL} | {TAL} | +| | | | | | +| | | | Csource registration creation | 12.2.2*; 9.2.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Context source registration by Id | [/csourceRegistrations/**{registrationId}**]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Csource registration retrieval by id | 12.3.2*; 9.3.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PATCH | {TAL} | {TAL} | +| | | | | | +| | | | Csource registration update by id | 12.2.3*; 9.3.3.2 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | {TAL} | {TAL} | +| | | | | | +| | | | Csource registration deletion by id | 12.2.4*; 9.3.3.3 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Context source registration subscription list | [/csourceSubscriptions/]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Retrieval of list of subscription to Csource registration | 12.4.5*; 9.4.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | {TAL} | {TAL} | +| | | | | | +| | | | Create subscription to Csource registration | 12.4.2*; 9.4.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Context source registration subscription by Id | [/csourceSubscriptions/**{subscriptionId}**]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Csource registration subscription retrieval by id | 12.4.4*; 9.5.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PATCH | {TAL} | {TAL} | +| | | | | | +| | | | Csource registration subscription update by id | 12.4.3*; 9.5.3.2 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | {TAL} | {TAL} | +| | | | | | +| | | | Csource registration subscription deletion by id | 12.4.6*; 9.5.3.3 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Operations. Create | [/entityOperations/create]{.HTML-Variable} | POST | {TAL} | {TAL} | +| | | | | | +| | | | Batch Entity creation | 10.3.2*; 7.7.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Operations. Upsert | [/entityOperations/upsert]{.HTML-Variable} | POST | {TAL} | {TAL} | +| | | | | | +| | | | Batch Entity creation or update ([upsert]{.HTML-Variable}) | 10.3.3*; 7.8.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Operations. Update | [/entityOperations/update]{.HTML-Variable} | POST | {TAL} | {TAL} | +| | | | | | +| | | | Batch Entity update | 10.3.4*; 7.9.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Operations. Delete | [/entityOperations/delete]{.HTML-Variable} | POST | {TAL} | {TAL} | +| | | | | | +| | | | Batch Entity deletion | 10.3.6*; 7.11.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Operations. Query | [/entityOperations/query]{.HTML-Variable} | POST | {TAL} | {TAL} | +| | | | | | +| | | | Query entities based on POST | 10.4.3*; 7.12.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Entity Operations. | [/entityOperations/merge]{.HTML-Variable} | POST | {TAL} | {TAL} | +| | | | | | +| Merge | | | Batch Entity merge | 10.3.5*; 7.10.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Temporal Evolution of Entities | [/temporal/entities/]{.HTML-Variable} | GET / HEAD | {TAL} | {TAL} | +| | | | | | +| | | | Query Temporal Evolution of Entities | 11.3.3*; 8.2.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | {TAL} | {TAL} | +| | | | | | +| | | | Temporal Evolution of an Entity creation | 11.2.2*; 8.2.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Temporal Evolution of an Entity by id | [/temporal/entities/**{entityId}**]{.HTML-Variable} | GET / HEAD | Temporal Evolution of an Entity retrieval by id | 11.3.2*; 8.3.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | Temporal Evolution of an Entity deletion by id | 11.2.7*; 8.3.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Temporal Representation of Attribute List | [/temporal/entities/**{entityId}**/attrs]{.HTML-Variable} | POST | Temporal Evolution of Attribute of an Entity instance addition | 11.2.3*; 8.4.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Temporal Representation of Attribute by id | [/temporal/entities/**{entityId}**/ | DELETE | Attribute from Temporal Evolution of an Entity deletion | 11.2.4*; 8.5.3.1 | +| | attrs/**{attrId}**]{.HTML-Variable} | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Temporal Representation of Attribute Instance by id | [/temporal/entities/**{entityId}**/ | PATCH | Attribute Instance from Temporal Evolution of an Entity update by instance id | 11.2.5*; 8.6.3.1 | +| | attrs/**{attrId}**/**{instanceId}**]{.HTML-Variable} | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | Attribute Instance from Temporal Evolution of an Entity deletion by instance id | 11.2.6*; 8.6.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Create EntityMap for Query Temporal Evolution of Entities | [/temporal/entityMaps]{.HTML-Variable} | GET / HEAD | Query temporal evolution of entities for creating entity map | 14.6*; | +| | | | | 11.3.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | Query temporal evolution of entities for creating entity map based on POST | 14.6*; | +| | | | | 11.3.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Temporal Query Operation | [/temporal/entityOperations/query]{.HTML-Variable} | POST | Query Temporal Evolution of Entities based on POST | 11.3.3*; 7.12.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Add and List _`@context`_ | [/jsonldContexts/]{.HTML-Variable} | GET / HEAD | List all cached _`@contexts`_ | 13.3*; 10.2.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | Add a user _`@context`_ to the internal cache | 13.2*; 10.2.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Serve, Delete and Reload _`@context`_ | [/jsonldContexts/**{contextId}**]{.HTML-Variable} | GET / HEAD | Serve one specific user _`@context`_ | 13.4*; 10.3.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | Delete one specific _`@context`_ from internal cache, possibly re-inserting a freshly | 13.5*; 10.3.3.2 | +| | | | downloaded copy of it | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Create EntityMap for Query Entities | [/entityMaps/]{.HTML-Variable} | GET / HEAD | Query entities for creating entity map | 14.5*; | +| | | | | 11.2.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | POST | Query entities for creating entity map based on POST | 14.5*; | +| | | | | 11.2.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Retrieve, Update and Delete Entity Maps | [/entityMaps/**{entityMapId}**]{.HTML-Variable} | GET / HEAD | EntityMap Retrieval by id | 14.2*; 11.4.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PATCH | EntityMap Update by id | 14.3*; 11.4.3.2 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | EntityMap Deletion by id | 14.4*; 11.4.3.3 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Retrieve Context Source Identity Information | [/info/sourceIdentity]{.HTML-Variable} | GET / HEAD | Context Source Identity Retrieval | 15.2*; 12.2.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Create Snapshot or Purge Snapshots | [/snapshots/]{.HTML-Variable} | POST | Create Snapshot | 16.2*; | +| | | | | 13.2.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | Purge Snapshots | 16.7*; | +| | | | | 13.2.3.2 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Retrieve and Update Snapshot Status or Delete Snapshot | [/snapshots/**{snapshotId}**]{.HTML-Variable} | GET / HEAD | Retrieve Snapshot Status | 16.4*; | +| | | | | 13.3.3.1 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | PATCH | Update Snapshot Status | 16.5*; | +| | | | | 13.3.3.2 | +| | | | | | +| | | | | | +| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | | DELETE | Delete Snapshot | 16.6*; | +| | | | | 13.3.3.3 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| Clone Snapshot | [/snapshots/**{snapshotId}**/clone]{.HTML-Variable} | POST | Clone Snapshot | 16.3*; | +| | | | | 13.4.3.1 | +| | | | | | +| | | | | | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +| | +| >>> [!note] | +| In the “Clauses” column, entries marked with an asterisk (*) indicate a reference to note [n.1]. | +| >>> | +| | ++-----------------------------------------------------------+---------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ +::: + + + +For every defined resource URI defined above, it shall be possible to retrieve +information about the communication options available on that resource using the +OPTIONS method. The response being an ["Allow"]{.HTML-Code} header field in the +response containing a list of the target resource's currently supported methods. + +Where defined, a HEAD request shall function in the same manner as a GET +request, but shall omit the body in the response. The response code 204 No +Content shall be used on success. diff --git a/md/clause-6.md b/md/clause-6.md new file mode 100644 index 0000000000000000000000000000000000000000..e5dbf6e9c43239cd74931914b988c2591600ce25 --- /dev/null +++ b/md/clause-6.md @@ -0,0 +1,921 @@ +# 6 Common behaviours + +## 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 [n.5], [n.6] verbs, request and response +payload bodies. + +A non-normative OAS specification [i.3] of the referred HTTP binding can be +found at [i.4]. + +## 6.2 General mapping to HTTP + +### 6.2.1 Introduction + +Context broker implementations are general-purpose servers as defined by IETF +9110 [n.5], and in this respect all standard HTTP verbs GET, HEAD, POST, PATCH, +PUT, DELETE and OPTIONS shall be recognised. + +### 6.2.2 HTTP request preconditions + +For HTTP POST, PATCH and PUT requests implementations shall check the following +preconditions: + +- 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 [n.10]. 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 [n.1] ~clause 10.4.3) and "Query Temporal Evolutions of Entities" +(see [n.1] ~clause 11.3.3), 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"]{.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 9110 [n.5], 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]{.HTML-Error} 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"]{.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}: + +- For Context Information Consumption operations only, specifically "Retrieve + Entity" (see [n.1] ~clause 10.4.2) and "Query Entity" (i.1] ~clause 10.4.3) + 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.2.3 HTTP response common requirements + +Implementations shall honour the Accept header provided by HTTP requests as +mandated by clause 6.2.2: + +- 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 [n.11], section 6.2. + + - If the Prefer header [n.12] is set to + ["ngsi-ld=<​version>"]{.HTML-Code} then implementations shall + set the Preference-Applied header to + ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the returned + response indicating which version of the NGSI-LD specification the payload + body conforms to, as mandated in [n.1] ~clause 9.5.3. + +- 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`_. + + - If the Prefer Header [n.12] is set to + ["ngsi-ld=<​version>"]{.HTML-Code} then implementations shall + set Preference-Applied header to + ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the returned + response indicating which version of the NGSI-LD specification the payload + body conforms to, as mandated in [n.1] ~clause 9.5.3. + +- If the target response's MIME type is ["application/geo+json"]{.HTML-Code} and + the Prefer Header [n.12] 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 [n.12] is set to ["body=json"]{.HTML-Code} such response + shall include a Link to the associated JSON-LD _`@context`_ as mandated by + [n.11], 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.2.4 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, HEAD or DELETE, then the associated JSON-LD + _`@context`_ shall be obtained from a Link header [n.13] as mandated by + JSON-LD [n.11], section 6.2. In the absence of such Link header, then the + associated _`@context`_ shall be the default JSON-LD _`@context`_. + + + +>>> [!tip] 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). + +>>> + + + +- 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 [n.11], 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]{.HTML-Error} 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]{.HTML-Error} 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]{.HTML-Error}. + +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, HEAD and DELETE operations always take their input +_`@context`_ from the JSON-LD Link Header. + +## 6.3 Errors and error handling + +### 6.3.1 Introduction + +This clause defines error handling and how errors are expresssed within the HTTP +Binding of the NGSI-LD API. + +### 6.3.2 Error types + +This clause associates API error types (which shall be contained in the response +payload body) defined by [n.1] ~clause 8.3.2 with HTTP status codes as shown in +Table+++below. + + + +::: TH +Table: 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: + +- "Method Not Allowed" (405) which shall be raised when a client invokes a + recognised but unsupported HTTP verb over a resource. Implementations shall + provide the allowed HTTP methods as mandated by IETF RFC 9110 [n.5] 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) 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}. +- "Not Implemented" (501) which shall be raised when a client invokes an HTTP + verb that is unrecognized or not implemented. Note that as a general-purpose + server, a Context broker shall recognise the methods GET and HEAD on all + endpoints. + +### 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.3 depending on error type. +- Payload body: A JSON object including all the terms defined by [n.1] ~clause + 8.3.3. + +### 6.3.4 Expiration time for cached \@contexts + +Implementations shall comply with the Expires header field (section 5.3 of IETF +RFC 7234 [n.14]) or a max-age or s-maxage response directive of Cache-Control +header field (section 5.2.2 of IETF RFC 7234 [n.14]) 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 [n.14] section 4.2.2) expiration time when an explicit time is not +specified. + +### 6.3.5 Distributed operations caching and timeout behaviour + +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 TTable+++below) 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"]{.HTML-Code} shall +be included. The value shall match the IANA Warning Code [n.15] 110 - Response +is Stale. + +["NGSILD-Warning"]{.HTML-Code} HTTP headers shall also be used to indicate +instances of abnormal behaviour for distributed HTTP GET and HEAD operations +performed over the resources /entities and /entities/{entity-id}. + + + +::: TH +Table: 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: + +- 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: + +- 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 [n.1] ~Table 5.2.6.5.3-1) has been +reached. + +### 6.3.6 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]{.HTML-Error} should be returned. + +## 6.4 Mapping NGSI-LD features to URI parameters and HTTP headers + +### 6.4.1 Introduction + +This clause defines the common input parameters and HTTP Response Headers +required to be able to express data and within the NGSI-LD API. + +### 6.4.2 Representation of Entities + +For HTTP GET and POST operations corresponding to "Retrieve Entity" (see [i.5] +~clause 10.4.2) and "Query Entities" ( see [n.1] ~clause 10.4.2 10.4.3), +[Context Broker]{.HTML-Keyboard} implementations shall support the parameter +specified in Table+++below, 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. + + + +::: TH +Table: 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 in [n.1] ~clause 5.3.2.2 and 5.3.3.3. | +| | | | | +| | | | When its value is ["concise"]{.HTML-Code}, a concise lossless representation of | +| | | | Entities shall be provided as defined in [n.1] ~clause 5.3.2.3 and 5.3.3.4. | +| | | | 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 in [n.1] ~clause 5.3.2.4 and 5.3.3.5. | +| | | | | +| | | | If the Accept Header is set to ["application/geo+json"]{.HTML-Code} | +| | | | the response will be in GeoJSON format as defined in [n.1] ~clause 5.3.3. | +| | | | | +| | | | | +| | | | | ++-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------+ +| 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 ~clause 5.3.2.2 and 5.3.3.3. | +| | | | | +| | | | When its value includes the keyword ["concise"]{.HTML-Code}, a concise | +| | | | lossless representation of Entities shall be provided as defined in | +| | | | [n.1] ~clause 5.3.2.3 and 5.3.3.4. 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 in [n.1] ~clause 5.3.2.4 and 5.3.3.5. | +| | | | | +| | | | If the Accept Header is set to ["application/geo+json"]{.HTML-Code} | +| | | | the response will be in GeoJSON format as defined as defined in [n.1] ~clause 5.3.3. | +| | | | | ++-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------+ +::: + + + +### 6.4.3 Simplified or aggregated temporal representation of Entities + +For HTTP GET and POST operations corresponding to "Retrieve Temporal Evolution +of an Entity" (see clause 11.3.2) and "Query Temporal Evolution of Entities" +(see clause 11.3.3), implementations shall support the parameter specified in +Table+++below. + + + +::: TH +Table: 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 [n.1] ~clause 5.3.2.6. | +| | | | | +| | | | When its value is ["aggregatedValues"]{.HTML-Code}, an aggregated temporal representation of entities shall be provided as defined by [n.1] ~clause 5.3.2.7. | ++-----------------+---------------------------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 5.3.2.6. | +| | | | | +| | | | When its value includes the keyword ["aggregatedValues"]{.HTML-Code}, an aggregated temporal representation of entities shall be provided as defined | +| | | | by [n.1] ~clause 5.3.2.7. | +| | | | | +| | | | 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.4.4 GeoJSON representation of spatially bound Entities + +For HTTP GET and POST operations corresponding to "Retrieve Entity" (see [i.5] +~clause 10.4.2) and "Query Entities" (see [n.1] ~clause 10.4.3), 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 +[n.1] ~clause 5.3.3. + +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. + + + +::: TH +Table: Selecting a geometry +::: + +::: TAL ++------------------+-----------------+-----------------+-----------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++==================+=================+=================+=====================================================+ +| geometryProperty | String | 0..1 | If not present, ["location"]{.HTML-Code} is used. | ++------------------+-----------------+-----------------+-----------------------------------------------------+ +::: + + + +### 6.4.5 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" ([n.1] ~clause 10.4.3) and "Query +Temporal Evolutions of Entities" (see [n.1] ~clause 11.3.3), implementations +shall support the parameter specified in Table +++below. Implementations shall +not raise an error if they do not hold system generated temporal attributes. + + + +::: TH +Table: 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.4.6 Counting number of results + +This clause implements the behaviour described in [n.1] ~clause 7.5, in case of +HTTP binding. + +For HTTP operations corresponding to the operations listed in [n.1] ~clause 7.4 +(see Table 5-1 for a list of HTTP operations with their corresponding clauses), +implementations shall support the HTTP query parameter specified in +Table+++below. + + + +::: TH +Table: 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]{.HTML-Error} error. + +### 6.4.7 Pagination + +For HTTP operations corresponding to the operations listed in [n.1] ~clause 7.4 +(see Table 5-1 for a list of HTTP operations with their corresponding clauses), +implementations shall support the HTTP query parameter specified in +Table+++below. + + + +::: TH +Table: 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. 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 [n.1] ~clause 7.4.2. 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 +[n.13], ~clause 3, as follows: + +- The pointers to the next and previous pages (when needed as mandated by clause + [n.1] ~clause 7.4.2) 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"]{.HTML-Code}, registered under the IANA Registry of Link Relation + Types [n.16]. + - 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 [n.16]. + +- At least, the ["type"]{.HTML-Code} Link Target Attribute shall be included by + the previously described serialized Link Header, as mandated by IETF RFC 8288 + [n.13], clause 3.4, 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). + + + +>>> [!tip] 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 [n.1] ~clause 7.2.3 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+++above and the _`offset`_ parameter as +specified in Table+++below, 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`_. + + + +::: TH +Table: Pagination: offset parameter +::: + +::: TAL ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 [Temporal Evolution of Entities]{.HTML-Keyboard}, implementations +shall use the Partial Content Response (206) as specified by IETF RFC 7233 +[n.17], ~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"]{.HTML-Code} header field +with the following contents: + +- ["unit"]{.HTML-Code} shall be equal to ["DateTime"]{.HTML-Code}; +- ["range-start"]{.HTML-Code} and ["range-end"]{.HTML-Code} shall be of type + _[DateTime]{.HTML-Definition}._ They depend on the requested time relationship + _`timerel`_ (as defined by [n.1] ~clause 7.2.6), as follows: + + - If the _`lastN`_ parameter is present, pagination shall happen "backwards": + + - ["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`_. + + - If the _`lastN`_ parameter is **not** present, pagination shall happen + "forwards": + - ["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 ["\*"]{.HTML-Code}. + +### 6.4.8 Tenant specification + +If the system implementing the NGSI-LD API supports multi-tenancy as described +in [n.1] ~clause 7.8, the [Tenant]{.HTML-Keyboard}, to which the NGSI-LD HTTP +operation is targeted, is specified as the HTTP header +["NGSILD-Tenant"]{.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-Tenant"]{.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-Tenant"]{.HTML-Code} HTTP header +(clause 6.5.2). + +### 6.4.9 Snapshot specification + +If the system implementing the NGSI-LD API supports Snapshots as described in +[n.1] ~clause 7.9, 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.5.2). + +### 6.4.10 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 [n.18], is found set to +[]{.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 +[n.1] ~clause 8.2.3) through amending the payload body and applying the +fallbacks defined within [n.1] ~clause 9.5.3. + +### 6.4.11 Limiting distributed operations + +The parameter described in this clause limits the execution of an operation to a +local [Context Source]{.HTML-Definition} or [Context Broker ]{.HTML-Definition} +([n.1] ~clause 8.6). It amends the matching [Context Source +Registrations]{.HTML-Keyboard} behaviour as described in [n.1] ~clause 9.4, in +the case of the HTTP binding in order to avoid cascading distributed operations +(see [n.1] ~clause 9.7). 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+++below. The Registry API operations are always local and thus are not +included here. Operations on a Snapshot (see [n.1] ~clause 7.9) are always +implicitly local scope, overriding setting the _`local`_ parameter to _`false`_, +i.e. such a setting is to be ignored by implementations. + + + +::: TH +**Table: 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 [n.1] ~clause 9.7). | ++-----------------+-----------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +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 [n.19]) as specified in Table+++below. 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 [n.1] ~clause 5.2.6.5.6) as the +pseudonym. + + + +::: TH +Table: Request Headers +::: + +::: TAL ++-----------------+---------------------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=============================================+=================+===============================================================================================================================================+ +| Via | String as defined in IETF RFC 7230 [n.19] | 0..1 | If present, the listing of previously encountered [Context Sources]{.HTML-Keyboard} supplied is used when determining matching registrations. | ++-----------------+---------------------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 6.5 Common operation behaviours + +### 6.5.1 Introduction + +This clause defines operational behaviour within the HTTP Binding of the NGSI-LD +API. + +### 6.5.2 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 +[n.1] ~clauses 5.2.6.5.2, 5.2.6.7.3, 5.2.6.7.4 and 5.2.6.6.1). For the HTTP +binding, the protocol part of the endpoint URI is _`http`_ or _`https`_. + + + +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 +[n.11], section 6.2 (to the default JSON-LD _`@context`_ if none available). + +If the optional array (of KeyValuePair type, as defined by [n.1] ~clause +5.2.6.6.3) _`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]{.HTML-Definition}. "Key" and "value" members shall adhere to IETF +RFC 7230 [n.19] 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 +[n.11], 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.5.3 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 [n.1] ~clause 5.2.6.5). 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} 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 +[n.11], section 6.2 (to the default JSON-LD _`@context`_ if none available). + +If the optional array (of [KeyValuePair]{.HTML-Definition} type, as defined by +[n.1] ~clause 5.2.6.6.3 _`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]{.HTML-Definition}. "Key" and "value" members shall adhere to IETF +RFC 7230 [n.19] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and +Routing definitions concerning HTTP headers. + +### 6.5.4 Extra information to provide when contacting Context Sources + +As specified in [i.5] clauses 9.5.1and 9.5.2, extra information to be provided +when contacting a [Context Source]{.HTML-Keyboard} can be specified in the +optional array (of [KeyValuePair]{.HTML-Definition} type, as defined by [i.5] +~clause 5.2.6.6.3) _`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 [n.11], 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]{.HTML-Definition}, 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 [n.19] 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"]{.HTML-Code}, take precedence and cannot be overridden using +_`contextSourceInfo`_. The same applies for headers generally set by HTTP +itself, e.g. Content-length. diff --git a/md/clause-7.md b/md/clause-7.md new file mode 100644 index 0000000000000000000000000000000000000000..4700ccfa9d182c94c906528fc0a1fdad9b244dad --- /dev/null +++ b/md/clause-7.md @@ -0,0 +1,2432 @@ +# 7 Core API resources + +## 7.1 Introduction + +This clause describes the resources that are part of the Core API. Each resource +is described in a separate section, which includes: + +- A brief description of the resource and its purpose. +- The resource definition, including the URI path and any path parameters. +- The resource methods supported, including the HTTP methods, request + parameters, and response formats. + +## 7.2 Resource: entities/ + +### 7.2.1 Description + +This resource represents the entities known to an NGSI-LD system. + +### 7.2.2 Resource definition + +Resource URI: + +- _`/entities/`_ + +### 7.2.3 Resource methods + +### 7.2.3.1 GET/HEAD + +This method is associated to the operation "Query Entities" and shall exhibit +the behaviour defined by [n.1] ~clause 10.4.3, 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 7.12. +Figure+++below shows the query entities interaction. + + + +::: FL + +::: + +::: TF +Figure: Query Entities interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in Table+++below, the request headers that shall be supported by implementations +are those defined in Table+++below+++below and Table+++below+++below+++below +describes the request body and possible responses. + + + +::: TH +Table: 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 [n.1] ~clause 8.6). | 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 [n.20]), 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 [n.1] ~clause 7.2.4. 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 [n.1] ~clause 7.2.3. | ++-------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 [n.1] ~clause 8.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 [n.21] format [n.21], 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 [n.1] ~clause 7.2.4. 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 [n.1] ~clause 8.6). | | ++-------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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]{.HTML-Definition} that contains the geospatial data that will be used to resolve the geoquery. By default, will be _`location`_ (see [n.1] ~clause 5.2.6.4.5). | +| | | | | +| | | It shall be ignored unless a _`geoquery`_ is present. | | ++-------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| georel | String | 0..1 | Geo relationship as per [n.1] ~clause 7.2.4. 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 [n.22] | 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 [n.1] ~clause 7.7). 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 [n.1] ~clause 7.6.2. 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 [n.1] ~clause 7.2.4. 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]{.HTML-Definition}) as defined by the GeoJSON specification (IETF RFC 7946 [n.23]). 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 [n.1] ~clause 7.2.3. | +| | | | | +| | | At least one among: _`type`_, _`attrs`_, _`q`_, or _`georel`_ shall be present, unless the execution of the request is limited to local scope (see [n.1] ~clause 8.6). | | ++-------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| scopeQ | String | 0..1 | Scope query (see [n.1] ~clause 7.2.5). | ++-------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 | Selection of Entity Types as per [n.1] ~clause 7.2.2. ["\*"]{.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 [n.1] ~clause 8.6). | | ++-------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: 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. | ++------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Query Entities request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 | +| +---------------------------------------------+-------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | {TAL} | {TAL} | 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. | +| +---------------------------------------------+-------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | {TAL} | {TAL} | {TAL} | As above, but returning an **altered response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [n.1] ~clause 9.5.3. | +| | | | | | +| | 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 [n.24]) | 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 [n.24]) | 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.4.2. | ++---------------+---------------------------------------------+-------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +### 7.2.3.2 POST + +This method is bound to the operation "Create Entity" and shall exhibit the +behaviour defined by [n.1] ~clause 10.2.2, taking the entity to be created from +the HTTP request payload body. Figure+++below shows the Create Entity +interaction and Table+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Create Entity interaction +::: + + + + + +::: TH +Table: Create Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +### 7.2.3.3 DELETE + +This method is associated to the operation "Purge Entities" and shall exhibit +the behaviour defined by [n.1] ~clause 10.2.12, providing entities as part of +the HTTP response payload body. Figure+++below shows the query entities +interaction. + + + +::: FL + +::: + +::: TF +Figure: Purge Entities interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in Table+++below, the request headers that shall be supported by implementations +are those defined in Table+++below+++below and Table+++below+++below+++below +describes the request body and possible responses. + + + +::: TH +Table: Purge Entities URL parameters +::: + +::: TAL ++------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++==================+===========================================+======================================================================================================================================================================================================================================================================================================================================================================================================================================================================+==========================================================================================================================================================================================================================================================+ +| coordinates | String | 0..1 | Coordinates serialized as a string as per [n.1] ~clause 7.2.4. 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 see [n.1] ~clause 7.2.3. | ++------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 [n.1] ~clause 7.2.4. 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 [n.1] ~clause 8.6). | | ++------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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]{.HTML-Definition} that contains the geospatial data that will be used to resolve the geoquery. By default, will be _`location`_ (see [n.1] ~clause 5.2.6.4.5). | +| | | | | +| | | It shall be ignored unless a _`geoquery`_ is present. | | ++------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| georel | String | 0..1 | Geo relationship as per [n.1] ~clause 7.2.4. 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 [n.22] | 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 [n.1] ~clause 7.2.3. | +| | | | | +| | | At least one among: _`type`_, _`attrs`_, _`q`_, or _`georel`_ shall be present, unless the execution of the request is limited to local scope (see [n.1] ~clause 8.6). | | ++------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| scopeQ | String | 0..1 | Scope query (see [n.1] ~clause 7.2.5). | ++------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. ["\*"]{.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 [n.1] ~clause 8.6). | | ++------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: 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. | ++------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Purge Entities request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.3 Resource: entities/{entityId} + +### 7.3.1 Description + +This resource represents an entity known to an NGSI-LD system. + +### 7.3.2 Resource definition + +Resource URI: + +- _`/entities/{entityId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: URI variables +::: + +::: TAL ++-----------------------------------+----------------------------------------+ +| Name | Definition | ++===================================+========================================+ +| entityId | Id (URI) of the entity to be retrieved | ++-----------------------------------+----------------------------------------+ +::: + + + +### 7.3.3 Resource methods + +#### 7.3.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Entity" and shall exhibit +the behaviour defined by [n.1] ~clause 10.4.2. The Entity identifier is the +value of the resource URI variable "entityId". Figure+++below shows the retrieve +entity interaction. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Entity interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below, +the request headers that shall be supported by implementations are those defined +in Table+++below+++below and Table+++below+++below+++below describes the request +body and possible responses. + + + +::: TH +Table: 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]{.HTML-Variable} 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 [n.1] ~clause 8.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 [n.21] 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]{.HTML-Definition} 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 [n.1] ~clause 7.7). 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 [n.1] ~clause 7.2.2. | ++-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: 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. | ++------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Retrieve Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | 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"]{.HTML-Code} 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 [n.1] ~clause 9.5.3. | +| | | | | | +| | | | | 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]{.HTML-Definition} 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 [n.24]) | 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 [n.24]) | 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 [n.24]) | 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.4.2. | ++---------------+---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.3.3.2 PATCH + +This method is bound to the "Merge Entity" operation and shall exhibit the +behaviour defined by [n.1] ~clause 10.2.9. 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+++below shows the Merge Entity +interaction. + + + +::: FL + +::: + +::: TF +Figure: Merge Entity interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below +and Table+++below+++below describes the request body and possible responses. + + + +::: TH +Table: 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 [n.1] clause 5.3.2.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]{.HTML-Error} 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]{.HTML-Definition} 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 [n.1] ~clause 5.2.2.4). | +| | | | | +| | | | 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 [n.1] clause 5.3.2.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 [n.1] ~clause 7.2.2. | ++-----------------+---------------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Merge Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. | ++---------------+---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.3.3.3 PUT + +This method is bound to the "Replace Entity" operation and shall exhibit the +behaviour defined by [n.1] ~clause 10.2.10. 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+++below shows the Replace +Entity interaction. + + + +::: FL + +::: + +::: TF +Figure: Replace Entity interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below +and Table+++below+++below describes the request body and possible responses. + + + +::: TH +Table: Replace Entity URL parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+========================================================+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +::: + + + + + +::: TH +Table: Replace Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. | ++---------------+---------------------------------------------+-------------+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.3.3.4 DELETE + +This method is associated to the operation "Delete Entity" and shall exhibit the +behaviour defined by [n.1] ~clause 10.2.8. The Entity identifier is the value of +the resource URI variable "entityId". Figure+++below shows the delete entity +interaction. + + + +::: FL + +::: + +::: TF +Figure: Delete Entity interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below +and Table+++below+++below describes the request body and possible responses. + + + +::: TH +Table: Delete Entity URL parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+========================================================+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +::: + + + + + +::: TH +Table: Delete Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.4 Resource: entities/{entityId}/attrs/ + +### 7.4.1 Description + +This resource represents all the Attributes (Properties or Relationships) of an +NGSI-LD Entity. + +### 7.4.2 Resource definition + +Resource URI: + +- _`/entities/{entityId}/attrs`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: URI variables +::: + +::: TAL ++-----------------------------------+-----------------------------------+ +| Name | Definition | ++===================================+===================================+ +| entityId | Id (URI) of the concerned entity | ++-----------------------------------+-----------------------------------+ +::: + + + +### 7.4.3 Resource methods + +#### 7.4.3.1 POST + +This method is bound to the "Append Attributes" operation and shall exhibit the +behaviour defined by [n.1] ~clause 10.2.4. 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+++below shows the Append Attributes +interaction. + + + +::: FL + +::: + +::: TF +Figure: Append Attributes interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below +and Table+++below+++below describes the request body and possible responses. + + + +::: TH +Table: 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 [n.1] ~clause 7.2.2. | ++-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Append Attributes request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.4.3.2 PATCH + +This method is bound to the "Update Attributes" operation and shall exhibit the +behaviour defined by [n.1] ~clause 10.2.3. 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+++below shows the Update Attributes +interaction. + + + +::: FL + +::: + +::: TF +Figure: Update Attributes interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below +and Table+++below+++below describes the request body and possible responses. + + + +::: TH +Table: Update Attributes URL parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+========================================================+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +::: + + + + + +::: TH +Table: Update Attributes request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.1] ~clause 5.2.6.8.5) | +| | | | | 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.5. | +| +---------------------------------------------+-------------+---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. | ++---------------+---------------------------------------------+-------------+---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.5 Resource: entities/{entityId}/attrs/{attrId} + +### 7.5.1 Description + +This resource represents an attribute (Property or Relationship) of an NGSI-LD +Entity. + +### 7.5.2 Resource definition + +Resource URI: + +- _`/entities/{entityId}/attrs/{attrId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: URI variables +::: + +::: TAL ++-----------------------------------+-------------------------------------------+ +| Name | Definition | ++===================================+===========================================+ +| entityId | Id (URI) of the concerned entity | ++-----------------------------------+-------------------------------------------+ +| attrId | Attribute name (Property or Relationship) | ++-----------------------------------+-------------------------------------------+ +::: + + + +### 7.5.3 Resource methods + +#### 7.5.3.1 GET/HEAD + +#### 7.5.3.2 PATCH + +This method is bound to the "Partial Attribute Update" operation and shall +exhibit the behaviour defined by [n.1] ~clause 10.2.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". The Entity Fragment shall be +contained in the HTTP request payload body. Figure+++below shows the Partial +Attribute Update interaction. + + + +::: FL + +::: + +::: TF +Figure: Partial Attribute Update interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below +and Table+++below+++below describes the request body and possible responses. + + + +::: TH +Table: Partial Attribute Update URL parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+========================================================+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +::: + + + + + +::: TH +Table: Partial Attribute Update request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.5.3.3 PUT + +This method is bound to the "Replace Attribute" operation and shall exhibit the +behaviour defined by [n.1] ~clause 10.2.11. 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+++below shows the Replace Attribute +interaction. + + + +::: FL + +::: + +::: TF +Figure: Replace Attribute interaction +::: + + + +The URL parameters that shall be supported are those defined in Table+++below +and Table+++below+++below describes the request body and possible responses. + + + +::: TH +Table: Replace Attribute URL parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+========================================================+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | ++-----------------+-----------------+-----------------+--------------------------------------------------------+ +::: + + + + + +::: TH +Table: Replace Attribute request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.5.3.4 DELETE + +This method is associated to the operation "Delete Attribute" and shall exhibit +the behaviour defined by [n.1] ~clause 10.2.7. 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+++below shows the Delete Attribute +interaction, Table+++below shows the delete parameters to be supported and +Table+++below+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Delete Attribute interaction +::: + + + + + +::: TH +Table: 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 [n.1] ~clause 7.2.2. | ++-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Delete Attribute request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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]{.HTML-Definition} structure. | +| | | | | | +| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.5. | +| +---------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.6 Resource: entities/{entityId}/attrs/{attrId}/value + +### 7.6.1 Description + +This resources represents the value of an attribute of a Entity. + +### 7.6.2 Resource definition + +### 7.6.3 Resource methods + +#### 7.6.3.1 GET/HEAD + +#### 7.6.3.2 PUT + +## 7.7 Resource: entityOperations/create + +### 7.7.1 Description + +A sub-resource, pertaining to the entityOperations/ resource, intended to enable +batch entity creation for the NGSI-LD API. + +### 7.7.2 Resource definition + +Resource URI: + +- _`/entityOperations/create`_ + +### 7.7.3 Resource methods + +#### 7.7.3.1 POST + +This method is associated to the operation "Batch Entity Creation" and shall +exhibit the behaviour defined by [n.1] ~clause 10.3.2. Figure+++below shows the +operation interaction and Table+++below describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure: Batch Entity Creation interaction +::: + + + + + +::: TH +Table: Batch Entity Creation request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.8 Resource: entityOperations/upsert + +### 7.8.1 Description + +A sub-resource, pertaining to the entityOperations/ resource, intended to enable +batch entity creation or update for the NGSI-LD API. + +### 7.8.2 Resource definition + +Resource URI: + +- _`/entityOperations/upsert`_ + +### 7.8.3 Resource methods + +#### 7.8.3.1 POST + +This method is associated to the operation "Batch Entity Creation or Update +(Upsert)" and shall exhibit the behaviour defined by [n.1] ~clause 10.3.3. +Figure+++below shows the operation interaction and Table+++below describes the +request body and possible responses. + +The _`options`_ query parameter for this request can take the following values: + +- ["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 + +::: + +::: TF +Figure: Batch Entity Creation or Update interaction +::: + + + + + +::: TH +Table: Batch Entity Creation or Update request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.9 Resource: entityOperations/update + +### 7.9.1 Description + +A sub-resource, pertaining to the entityOperations/ resource, intended to enable +batch entity update for the NGSI-LD API. + +### 7.9.2 Resource definition + +Resource URI: + +- _`/entityOperations/update`_ + +### 7.9.3 Resource methods + +#### 7.9.3.1 POST + +This method is associated to the operation "Batch Entity Update" and shall +exhibit the behaviour defined by [n.1] ~clause 10.3.4. Figure+++below shows the +operation interaction and Table+++below describes the request body and possible +responses. + +The _`options`_ query parameter for this request can take the following values: + +- ["noOverwrite".]{.HTML-Code} Indicates that no attribute overwrite shall be + performed. + + + +::: FL + +::: + +::: TF +Figure: Batch Entity Update interaction +::: + + + + + +::: TH +Table: Batch Entity Update request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.10 Resource: entityOperations/merge + +### 7.10.1 Description + +A sub-resource, pertaining to the entityOperations/ resource, intended to enable +batch entity merge for the NGSI-LD API. + +### 7.10.2 Resource definition + +Resource URI: + +- _`/entityOperations/merge`_ + +### 7.10.3 Resource methods + +#### 7.10.3.1 POST + +This method is associated to the operation "Batch Entity Merge" and shall +exhibit the behaviour defined by [n.1] ~clause 10.3.5. Figure+++below shows the +operation interaction and Table+++below describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure: Batch Entity Merge interaction +::: + + + + + +::: TH +Table: Batch Entity Merge request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.11 Resource: entityOperations/delete + +### 7.11.1 Description + +A sub-resource, pertaining to the entityOperations/ resource, intended to enable +batch entity deletion for the NGSI-LD API. + +### 7.11.2 Resource definition + +Resource URI: + +- _`/entityOperations/delete`_ + +### 7.11.3 Resource methods + +#### 7.11.3.1 POST + +This method is associated to the operation "Batch Entity Delete" and shall +exhibit the behaviour defined by [n.1] ~clause 10.3.6. Figure+++below shows the +operation interaction and Table+++below describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure: Batch Entity Delete interaction +::: + + + + + +::: TH +Table: Batch Entity Delete request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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.5. | +| +---------------------------------------------+-------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.12 Resource: entityOperations/query + +### 7.12.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 7.2.3.1, which performs the "Query Entity" operation +(defined by [n.1] ~clause 10.4.3) by means of a GET method. The reason to +provide an alternative via POST is that, using GET: + +- 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. + +### 7.12.2 Resource definition + +Resource URI: + +- _`/entityOperations/query`_ + +### 7.12.3 Resource methods + +#### 7.12.3.1 POST + +This method is associated to the operation "Query Entities" and shall exhibit +the behaviour defined by [n.1] ~clause 10.4.3. Figure+++below shows the +operation interaction and Table+++below describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure: Query Entity via POST interaction +::: + + + + + +::: TH +Table: Query Entity via POST request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 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. | +| +---------------------------------------------+-------------+---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | 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 [n.1] ~clause 9.5.3. | +| | | | | | +| | | | | The response shall also include a ["Preference-Applied"]{.HTML-Code} HTTP header set to ["ngsi-ld="]{.HTML-Code}. | +| +---------------------------------------------+-------------+---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.13 Resource: subscriptions/ + +### 7.13.1 Description + +This resource represents the subscriptions known to an NGSI-LD system. + +### 7.13.2 Resource definition + +Resource URI: + +- _`/subscriptions/`_ + +### 7.13.3 Resource methods + +#### 7.13.3.1 GET/HEAD + +This method is associated to the operation "Query Subscriptions" and shall +exhibit the behaviour defined by [n.1] ~clause 10.5.5, providing the +subscription data as part of the HTTP response payload body. Figure+++below +shows the Query Subscriptions interaction. + + + +::: FL + +::: + +::: TF +Figure: Query Subscriptions interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in Table+++below and Table+++below+++below describes the request body and +possible responses. + + + +::: TH +Table: Query Subscriptions URL parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+-------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+=================================================+ +| limit | Number | 0..1 | Maximum number of subscriptions to be retrieved | ++-----------------+-----------------+-----------------+-------------------------------------------------+ +::: + + + + + +::: TH +Table: Query Subscriptions request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.13.3.2 POST + +This method is bound to the operation "Create Subscription" and shall exhibit +the behaviour defined by [n.1] ~clause 10.5.2, taking the subscription to be +created from the HTTP request payload body. Figure+++below shows the Create +Subscription interaction and Table+++below describes the request body and +possible responses. + + + +::: FL + +::: + +::: TF +Figure: Create Subscription interaction +::: + + + + + +::: TH +Table: Create Subscription request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.14 Resource: subscriptions/{subscriptionId} + +### 7.14.1 Description + +This resource represents a subscription known to an NGSI-LD system. + +### 7.14.2 Resource definition + +Resource URI: + +- _`/subscriptions/{subscriptionId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: URI variables +::: + +::: TAL ++-----------------------------------+----------------------------------------+ +| Name | Definition | ++===================================+========================================+ +| subscriptionId | Id (URI) of the concerned subscription | ++-----------------------------------+----------------------------------------+ +::: + + + +### 7.14.3 Resource methods + +#### 7.14.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Subscription" and shall +exhibit the behaviour defined by [n.1] ~clause 10.5.4. The subscription +identifier is the value of the resource URI variable "subscriptionId". +Figure+++below shows the Retrieve Subscription interaction and Table+++below +describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Subscription interaction +::: + + + + + +::: TH +Table: Retrieve Subscription request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.14.3.2 PATCH + +This method is associated to the operation "Update Subscription" and shall +exhibit the behaviour defined by [n.1] ~clause 10.5.3. The subscription +identifier is the value of the resource URI variable "subscriptionId". +Figure+++below shows the Update Subscription interaction and Table+++below +describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Update Subscription interaction +::: + + + + + +::: TH +Table: Update Subscription request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 7.14.3.3 DELETE + +This method is associated to the operation "Delete Subscription" and shall +exhibit the behaviour defined by [n.1] ~clause 10.5.6. The subscription +identifier is the value of the resource URI variable "subscriptionId". +Figure+++below shows the Delete Subscription interaction and Table+++below +describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Delete Subscription interaction +::: + + + + + +::: TH +Table: Delete Subscription request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.15 Resource: types/ + +### 7.15.1 Description + +This resource represents the entity types available in an NGSI-LD system. + +### 7.15.2 Resource definition + +Resource URI: + +- _`/types/`_ + +### 7.15.3 Resource methods + +#### 7.15.3.1 GET/HEAD + +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 [n.1] ~clauses +10.6.3 and 10.6.4 respectively. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Entity Types interaction +::: + + + +The request parameters that shall be supported are those defined in +Table+++below and Table+++below+++below describes the request body and possible +responses. + + + +::: TH +Table: 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 ([n.1] ~clause 5.2.6.10.3) is to be returned. | ++-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Retrieve Available Entity Types request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 ([n.1] ~clause 5.2.6.10.5) 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 ([n.1] ~clause 5.2.6.10.3) is to | +| | | | | be returned. | +| +---------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.16 Resource: types/{type} + +### 7.16.1 Description + +This resource represents the specified entity type for which entity instances +are available in an NGSI-LD system. + +### 7.16.2 Resource definition + +Resource URI: + +- _`/types/{type}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: 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. | ++-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +### 7.16.3 Resource methods + +#### 7.16.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Available Entity Type +Information" and shall exhibit the behaviour defined by [n.1] ~clause 10.6.5. +The entity type is the value of the resource URI variable "type". Figure+++below +shows the retrieve available entity type interaction. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Entity Type interaction +::: + + + +Table+++below describes the request body and possible responses. + + + +::: TH +Table: Retrieve Available Entity Type request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 1 | 404 Not Found | It is used when a client provided an entity type not known to the system, see clause 6.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.17 Resource: attributes/ + +### 7.17.1 Description + +This resource represents the attributes available in an NGSI-LD system. + +### 7.17.2 Resource definition + +Resource URI: + +- _`/attributes/`_ + +### 7.17.3 Resource methods + +#### 7.17.3.1 GET/HEAD + +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 [n.1] ~clauses 10.6.6 +and 10.6.7 respectively. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Attributes interaction +::: + + + +The request parameters that shall be supported are those defined in +Table+++below and Table+++below+++below describes the request body and possible +responses. + + + +::: TH +Table: 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 ([n.1] ~clause 5.2.6.10.1) is to be returned. | ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Retrieve Available Attributes request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 ([n.1] ~clause 5.2.6.10.2) 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 ([n.1] ~clause 5.2.6.10.1) is to | +| | | | | be returned. | +| +---------------------------------------------+-------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 7.18 Resource: attributes/{attrId} + +### 7.18.1 Description + +This resource represents the specified attribute that belongs to entity +instances existing within the NGSI-LD system. + +### 7.18.2 Resource definition + +Resource URI: + +- _`/attributes/{attrId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: 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. | ++-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +### 7.18.3 Resource methods + +#### 7.18.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Available Attribute +Information" and shall exhibit the behaviour defined by [n.1] ~clause 10.6.8. +The attribute is the value of the resource URI variable "attrId". Figure+++below +shows the retrieve available attribute information interaction. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Attribute Information interaction +::: + + + +Table+++below describes the request body and possible responses. + + + +::: TH +Table: Retrieve Available Attribute Information request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 1 | 404 Not Found | It is used when a client provided an attribute name not known to the system, see clause 6.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + diff --git a/md/clause-8.md b/md/clause-8.md new file mode 100644 index 0000000000000000000000000000000000000000..6e7d8ffb36de37d62312482ed7e7db61f01e186d --- /dev/null +++ b/md/clause-8.md @@ -0,0 +1,853 @@ +# 8 Temporal API resources + +## 8.1 Introduction + +Clause+++root defines the resources related to the temporal API. + +## 8.2 Resource: temporal/entities/ + +### 8.2.1 Description + +This resource represents the [Temporal Evolution of Entities]{.HTML-Keyboard} +known to an NGSI-LD system. + +### 8.2.2 Resource definition + +Resource URI: + +- _`/temporal/entities/`_ + +### 8.2.3 Resource methods + +#### 8.2.3.1 GET/HEAD + +This method is associated to the operation "Query Temporal Evolution of +Entities" and shall exhibit the behaviour defined by [n.1] ~clause 11.3.3, +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+++root.7. Figure+++below shows this interaction. + + + +::: FL + +::: + +::: TF +Figure: 8.2.3.1-1: Query Temporal Evolution of Entities interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in table 8.2.3.1-1 and table 8.2.3.1-2 describes the request body and possible +responses. + + + +::: TH +Table 8.2.3.1-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 [n.1] ~clause 5.3.2.7. 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 [n.1] ~clause 5.3.2.7. 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 [n.1] | Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved. | +| | | ~clause 8.6). | | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| collation | String | 0..1 | An ICU collation (see IETF RFC 6067 [n.20]), 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 [n.1] ~clause 7.2.4. 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 [n.1] ~clause 7.2.3. | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 [n.1] ~clause 8.5. | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| endTimeAt | String | 0..1 | It is representing the _`endTimeAt`_ parameter as defined by [n.1] ~clause 7.2.6. 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 [n.21] 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 [n.1] ~clause 7.2.4. It is part of geoquery. | +| | | | | +| | | It shall be 1 if _`georel`_ or _`coordinates`_ are present | | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| geoproperty | String | 0..1 | The name of the [GeoProperty]{.HTML-Definition} that contains the geospatial data that will be used to resolve the geoquery. By default, will be _`location`_. (See [n.1] ~clause 5.2.6.4.5). | +| | | | | +| | | It shall be ignored if no geoquery is present | | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| georel | String | 0..1 | Geo relationship as per [n.1] ~clause 7.2.4. 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 [n.22] | 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 [n.1] ~clause 7.6.2. 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 [n.1] ~clause 7.2.3. | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| scopeQ | String | 0..1 | Scope query (see [n.1] ~clause 7.2.5). | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 [n.1] ~clause 7.2.6. 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 [n.1] ~clause 5.2.4). | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timerel | String | 1 | It represents the temporal relationship as defined by [n.1] ~clause 7.2.6. Allowed values: ["before"]{.HTML-Code}, ["after"]{.HTML-Code}, ["between"]{.HTML-Code}. | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. ["\*"]{.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 [n.1] | | +| | | ~clause 8.6). | | ++--------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table 8.2.3.1-2: Query Temporal Evolution of Entities request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.1] ~clause 9.5.3. | +| | | | | | +| | | | | The response shall also include a ["Preference-Applied"]{.HTML-Code} HTTP header set to ["ngsi-ld="]{.HTML-Code}. | +| +---------------------------------------------+-------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 8.2.3.2 POST + +This method is associated to the operation "Create or Update Temporal Evolution +of an Entity" and shall exhibit the behaviour defined by [n.1] ~clause 11.2.2, +taking the temporal representation of Entity to be created from the HTTP request +payload body. Figure 8.2.3.2-1 shows this interaction and table 8.2.3.2-1 +describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: 8.2.3.2-1: Create or Update Temporal Evolution of an Entity interaction +::: + + + + + +::: TH +Table 8.2.3.2-1: Create or Update Temporal Evolution of an Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ member should convey more information about the error. | +| +---------------------------------------------+-------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 422 Unprocessable Entity | It is used to indicate that the operation is not available, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 8.3 Resource: temporal/entities/{entityId} + +### 8.3.1 Description + +This resource is associated to the [Temporal Evolution of an +Entity]{.HTML-Keyboard} known to an NGSI-LD system. + +### 8.3.2 Resource definition + +Resource URI: + +- _`/temporal/entities/{entityId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table 8.3.2-1: URI variables +::: + +::: TAL ++-----------------------------------+----------------------------------------+ +| Name | Definition | ++===================================+========================================+ +| entityId | Id (URI) of the entity to be retrieved | ++-----------------------------------+----------------------------------------+ +::: + + + +### 8.3.3 Resource methods + +#### 8.3.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Temporal Evolution of an +Entity" and shall exhibit the behaviour defined by [n.1] ~clause 11.3.2. The +Entity identifier is the value of the resource URI variable entityId. +Figure+++below shows the retrieve temporal representation of an entity +interaction. + + + +::: FL + +::: + +::: TF +Figure: 8.3.3.1-1: Retrieve Temporal Evolution of an Entity interaction +::: + + + +The URL parameters that shall be supported are those defined in table 8.3.3.1-1 +and table 8.3.3.1-2 describes the request body and possible responses. + + + +::: TH +Table 8.3.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 [n.1] ~clause 5.3.2.7. Only applicable if ["aggregatedValues"]{.HTML-Code} is present in the _`format`_ or _`options`_ parameter. | +| | | | | +| | | It shall be 1 if ["aggregatedValues"]{.HTML-Code} is present in the _`options`_ parameter | | ++--------------------+---------------------------------+-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| aggrPeriodDuration | String | 0..1 | It represents the duration of each period used for the aggregation as defined by [n.1] ~clause 5.3.2.7. 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 [n.1] ~clause 8.5. | ++--------------------+---------------------------------+-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| endTimeAt | String | 0..1 | It represents the _`endTimeAt`_ parameter as defined by [n.1] ~clause 7.2.6. It shall be a _DateTime_. | +| | | | | +| | | It shall be 1 if _`timerel`_ is equal to ["between"]{.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. | ++--------------------+---------------------------------+-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 [n.1] ~clause 7.2.6. 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 [n.1] clause ~5.2.4). | ++--------------------+---------------------------------+-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timerel | String | 0..1 | It represents the Temporal Relationship as defined by [n.1] ~clause 7.2.6. Allowed values: ["before"]{.HTML-Code}, ["after"]{.HTML-Code}, ["between"]{.HTML-Code}. | +| | | | | +| | | It shall be 1 if _`timeAt`_ is present | | ++--------------------+---------------------------------+-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table 8.3.3.1-2: Get Temporal Evolution of an Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.1] | +| | | | | ~clause 9.5.3. | +| | | | | | +| | | | | The response shall also include a ["Preference-Applied"]{.HTML-Code} HTTP header set to ["ngsi-ld="]{.HTML-Code}. | +| +---------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see Clause+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 8.3.3.2 DELETE + +This method is associated to the operation "Delete Temporal Evolution of an +Entity" and shall exhibit the behaviour defined by [n.1] ~clause 11.2.7. The +Entity identifier is the value of the resource URI variable entityId. +Figure+++below shows the delete entity interaction and Table+++below describes +the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: 8.3.3.2-1: Delete Temporal Evolution of an Entity interaction +::: + + + + + +::: TH +Table 8.3.3.2-1: Delete Temporal Evolution of an Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see Clause+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 8.4 Resource: temporal/entities/{entityId}/attrs/ + +### 8.4.1 Description + +This resource represents all the Attributes of a [Temporal Evolution of an +Entity]{.HTML-Keyboard}. + +### 8.4.2 Resource definition + +Resource URI: + +- _`/temporal/entities/{entityId}/attrs/`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table 8.4.2-1: URI variables +::: + +::: TAL ++-----------------------------------+-----------------------------------+ +| Name | Definition | ++===================================+===================================+ +| entityId | Id (URI) of the concerned entity | ++-----------------------------------+-----------------------------------+ +::: + + + +### 8.4.3 Resource methods + +#### 8.4.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 [n.1] ~clause 11.2.3. 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+++below +shows the Add Attributes interaction and Table+++below describes the request +body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: 8.4.3.1-1: Add Attributes to Temporal Evolution of an Entity interaction +::: + + + + + +::: TH +Table 8.4.3.1-1: Add Attributes to Temporal Evolution ofan Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see Clause+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 8.5 Resource: temporal/entities/{entityId}/attrs/{attrId} + +### 8.5.1 Description + +This resource represents an Attribute of a [Temporal Evolution of an +Entity]{.HTML-Keyboard}. + +### 8.5.2 Resource definition + +Resource URI: + +- _`/temporal/entities/{entityId}/attrs/{attrId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table 8.5.2-1: URI variables +::: + +::: TAL ++-----------------------------------+-------------------------------------------+ +| Name | Definition | ++===================================+===========================================+ +| entityId | Id (URI) of the concerned entity | ++-----------------------------------+-------------------------------------------+ +| attrId | Attribute name (Property or Relationship) | ++-----------------------------------+-------------------------------------------+ +::: + + + +### 8.5.3 Resource methods + +#### 8.5.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 [n.1] ~clause +11.2.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. +Figure+++below shows the "Delete Attribute from Temporal Evolution of an Entity" +interaction, table 8.5.3.1-1 shows the delete parameters to be supported and +table 8.5.3.1-2 describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: 8.5.3.1-1: Delete Attribute from Temporal Evolution of an Entity interaction +::: + + + + + +::: TH +Table 8.5.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. | ++-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table 8.5.3.1-2: Delete Attribute from Temporal Evolution ofan Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 8.6 Resource: temporal/entities/{entityId}/attrs/{attrId}/{instanceId} + +### 8.6.1 Description + +This resource represents an Attribute (Property or Relationship) instance of a +[Temporal Evolution of an Entity]{.HTML-Keyboard}. + +### 8.6.2 Resource definition + +Resource URI: + +- _`/temporal/entities/{entityId}/attrs/{attrId}/{instanceId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table 8.6.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 | ++-----------------------------------+------------------------------------------------------+ +::: + + + +### 8.6.3 Resource methods + +#### 8.6.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 +[n.1] ~clause 11.2.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. The instance identifier is the value of the resource URI variable +instanceId. Figure+++below shows the Modify Attribute instance interaction and +Table+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: 8.6.3.1-1: Modify Attribute instance from Temporal Evolution interaction +::: + + + + + +::: TH +Table 8.6.3.1-1: Modify Attribute instance fromTemporal Evolution request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 8.6.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 +[n.1] ~clause 11.2.6. 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+++below shows the Delete Attribute instance interaction and +Table+++below describes the request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: 8.6.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity interaction +::: + + + + + +::: TH +Table 8.6.3.2-1: Delete Attribute instance fromTemporal Evolution of an Entity request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | +| +---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 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+++clause-6+++root.3.2. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 8.7 Resource: temporal/entityOperations/query + +### 8.7.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+++root.2.3.1, which performs +the "Query [Temporal Evolution of Entities]{.HTML-Keyboard}" (defined by [n.1] +~clause 11.3.3) operation by means of a GET method. The reason to provide an +alternative via POST is that, using GET: + +- 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. + +### 8.7.2 Resource definition + +Resource URI: + +- _`/temporal/entityOperations/query`_ + +### 8.7.3 Resource methods + +#### 8.7.3.1 POST + +This method is associated to the operation "Query Temporal Evolution of +Entities" and shall exhibit the behaviour defined by [n.1] ~clause 11.3.3. +Figure+++below shows the operation interaction and Table+++below describes the +request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: 8.7.3.1-1: Temporal Query Entity via POST interaction +::: + + + + + +::: TH +Table 8.7.3.1-1: Temporal Query Entity via POST request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see Clause+++clause-6+++root.3.2. | +| | | | | | +| | | | | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + diff --git a/md/clause-9.md b/md/clause-9.md new file mode 100644 index 0000000000000000000000000000000000000000..07cd6d443d4349e8b883dea102bf9e0522ac37ed --- /dev/null +++ b/md/clause-9.md @@ -0,0 +1,742 @@ +# 9 Registry API resources + +## 9.1 Introduction + +Clause+++root defines the resources related to creating, managing, retrieving, +discovering and subscribing to Context Source Registrations. + +## 9.2 Resource: csourceRegistrations/ + +### 9.2.1 Description + +This resource represents the Context Source Registrations known to an NGSI-LD +system. + +### 9.2.2 Resource definition + +Resource URI: + +- _`/csourceRegistrations/`_ + +### 9.2.3 Resource methods + +#### 9.2.3.1 GET/HEAD + +This method is associated to the operation "Query Context Source Registrations" +and shall exhibit the behaviour defined by [n.1] ~clause 12.3.3, 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+++below shows the +Query Context Source Registrations interaction. + + + +::: FL + +::: + +::: TF +Figure: Query Context Source Registrations interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in Table 9.2.3.1-1 and Table 9.2.3.1-2 describes the request body and possible +responses. + + + + + +::: TH +Table: 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 [n.1] ~clause 7.2.4. 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 [n.1] ~clause 7.2.3. | ++------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| endTimeAt | String | 0..1 | It represents the _`endTimeAt`_ parameter as defined by [n.1] ~clause 7.2.6. | +| | | | | +| | | | 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 [n.1] ~7.2.4. 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 [n.1] ~clause 7.2.4. 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 [n.22] | 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 [n.1] ~clause 7.2.3. | +| | | | | +| | | At least one among: _`type`_, _`attrs`_, _`q`_, or _`georel`_ shall be present. | | ++------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| scopeQ | String | 0..1 | Scope query (see [n.1] ~clause 7.2.5). | ++------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timeAt | String | 0..1 | It represents the _`timeAt`_ parameter as defined by [n.1] ~clause 7.2.6. | +| | | | | +| | | | 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 [n.1] ~clause 5.2.4). | ++------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timerel | String | 0..1 | It represents the temporal relationship as defined by [n.1] ~clause 7.2.6. | +| | | | | +| | | | Allowed values: ["before"]{.HTML-Code}, ["after"]{.HTML-Code}, ["between".]{.HTML-Code} | ++------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | +| | | | | +| | | At least one among: _`type`_, _`attrs`_, _`q`_, or _`georel`_ shall be present. | | ++------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Retrieve Context Source Registrations request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 9.2.3.2 POST + +This method is bound to the operation "Register Context Source" and shall +exhibit the behaviour defined by [n.1] ~clause 12.2.2, taking the context source +registration to be created from the HTTP request payload body. Figure+++below +shows the Register Context Source interaction and Table 9.2.3.2-1 describes the +request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Register Context Source interaction +::: + + + + + +::: TH +Table: Register Context Source request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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 [n.24]) | 1 | 422 Unprocessable | It is used to indicate that the operation is not available see clause 6.3.2. | +| | | | | | +| | | | [Context Source Registration]{.HTML-Keyboard} | In the returned _ProblemDetails_ structure, the _`detail`_ attribute should convey more information about the error. | ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 9.3 Resource: csourceRegistrations/{registrationId} + +### 9.3.1 Description + +This resource represents the context source registration, identified by +registrationId, known to an NGSI-LD system. + +### 9.3.2 Resource definition + +Resource URI: + +- _`/csourceRegistrations/{registrationId}`_ + +Resource URI variables for this resource are defined in Table+++below. + + + +::: TH +Table: URI variables +::: + +::: TAL ++-----------------------------------+---------------------------------------------+ +| Name | Definition | ++===================================+=============================================+ +| registrationId | Id (URI) of the context source registration | ++-----------------------------------+---------------------------------------------+ +::: + + + +### 9.3.3 Resource methods + +#### 9.3.3.1 GET/HEAD + +This method is associated with the operation "Retrieve Context Source +Registration" and shall exhibit the behaviour defined by [n.1] ~clause 12.3.2. +The registration identifier is the value of the resource URI variable +"registrationId". Figure+++below shows the Retrieve Context Source Registration +interaction and Table 9.3.3.1-1 describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Context Source Registration interaction +::: + + + + + +::: TH +Table: Retrieve Context Source Registration request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 9.3.3.2 PATCH + +This method is bound to the "Update Context Source Registration" operation and +shall exhibit the behaviour defined by [n.1] ~clause 12.2.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+++below shows the Update +Context Source Registration interaction and Table 9.3.3.2-1 describes the +request body and possible responses. + + + +::: FL + +::: + +::: TF +Figure: Update Context Source Registration interaction +::: + + + + + +::: TH +Table: Update Context Source Registration request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 9.3.3.3 DELETE + +This method is associated to the operation "Delete Context Source Registration" +and shall exhibit the behaviour defined by [n.1] ~clause 12.2.4. The context +source registration identifier is the value of the resource URI variable +"registrationId". Figure+++below shows the Delete Context Source Registration +interaction and Table 9.3.3.3-1 describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure: Delete Context Source Registration interaction +::: + + + + + +::: TH +Table: Delete Context Source Registration request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 9.4 Resource: csourceSubscriptions/ + +### 9.4.1 Description + +This resource represents the context source registration subscriptions known to +an NGSI-LD system. + +### 9.4.2 Resource definition + +Resource URI: + +- _`/csourceSubscriptions/`_ + +### 9.4.3 Resource methods + +#### 9.4.3.1 GET/HEAD + +This method is bound to the operation "Create Context Source Registration +Subscription" and shall exhibit the behaviour defined by ~clause 12.4.2, taking +the context source registration subscription to be created from the HTTP request +payload body. Figure+++below shows the Create Context Source Registration +Subscription interaction and Table 9.4.3.1-1 describes the request body and +possible responses. + + + +::: FL + +::: + +::: TF +Figure: Create Context Source Registration Subscription interaction +::: + + + + + +::: TH +Table: Create Context Source Registration Subscription request bodyand possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 9.4.3.2 POST + +This method is associated to the operation "Query Context Source Registration +Subscriptions" and shall exhibit the behaviour defined by [n.1] ~clause 12.4.5, +providing the context source registration subscription data as part of the HTTP +response payload body. Figure+++below shows the Query Context Source +Registration Subscriptions interaction. + + + +::: FL + +::: + +::: TF +Figure: Query Context Source Registration Subscriptions interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in Table 9.4.3.2-1 and Table 9.4.3.2-2 describes the request body and possible +responses. + + + +::: TH +Table: Query Context Source Registration Subscriptions URL parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+-------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+=================================================+ +| limit | Number | 0..1 | Maximum number of subscriptions to be retrieved | ++-----------------+-----------------+-----------------+-------------------------------------------------+ +::: + + + + + +::: TH +Table: Query Context Source Registration Subscriptions request bodyand possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +## 9.5 Resource: csourceSubscriptions/{subscriptionId} + +### 9.5.1 Description + +This resource represents the context source registration subscription, +identified by subscriptionId, known to an NGSI-LD system. + +### 9.5.2 Resource definition + +Resource URI: + +- _`/csourceSubscriptions/{subscriptionId}`_ + +Resource URI variables for this resource are defined in Table 9.5.2-1. + + + +::: TH +Table: URI variables +::: + +::: TAL ++-----------------------------------+---------------------------------------------------------------------+ +| Name | Definition | ++===================================+=====================================================================+ +| subscriptionId | Id (URI) of the concerned context source registration subscription. | ++-----------------------------------+---------------------------------------------------------------------+ +::: + + + +### 9.5.3 Resource methods + +#### 9.5.3.1 GET/HEAD + +This method is associated to the operation "Retrieve Context Source Registration +Subscription" and shall exhibit the behaviour defined by ~clause 12.4.4. The +subscription identifier is the value of the resource URI variable +"subscriptionId". Figure+++below shows the Retrieve Context Source Registration +interaction and Table 9.5.3.1-1 describes the request body and possible +responses. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Context Source Registration Subscription interaction +::: + + + + + +::: TH +Table: Retrieve Context Source Registration Subscription request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 9.5.3.2 PATCH + +This method is associated to the operation "Update Context Source Registration +Subscription" and shall exhibit the behaviour defined by [n.1] ~clause 12.4.3. +The subscription identifier is the value of the resource URI variable +"subscriptionId". Figure+++below shows the Update Context Source Registration +Subscription interaction and Table 9.5.3.2-1 describes the request body and +possible responses. + + + +::: FL + +::: + +::: TF +Figure: Update Context Source Registration Subscription interaction +::: + + + + + +::: TH +Table: Update Context Source Registration Subscription request bodyand possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 9.5.3.3 DELETE + +This method is associated to the operation "Delete Context Source Registration +Subscription" and shall exhibit the behaviour defined by [n.1] ~clause 12.4.6. +The subscription identifier is the value of the resource URI variable +"subscriptionId". Figure+++below shows the Delete Context Source Registration +Subscription interaction and Table 9.5.3.3-1 describes the request body and +possible responses. + + + +::: FL + +::: + +::: TF +Figure: Delete Context Source Registration Subscription interaction +::: + + + + + +::: TH +Table: Delete Context Source Registration Subscription request bodyand possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| 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 [n.24]) | 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 [n.24]) | 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. | ++---------------+---------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + diff --git a/md/executive-summary.md b/md/executive-summary.md new file mode 100644 index 0000000000000000000000000000000000000000..28750c108be6d343899ced16698d2730ba4862ac --- /dev/null +++ b/md/executive-summary.md @@ -0,0 +1 @@ +# Executive summary diff --git a/md/foreword.md b/md/foreword.md new file mode 100644 index 0000000000000000000000000000000000000000..5bd0c17a21ea8ec149701c9ef4e3150fcc29d872 --- /dev/null +++ b/md/foreword.md @@ -0,0 +1,4 @@ +# Foreword + +This Technical Specification (TS) has been produced by ETSI Technical Committee +Data Solutions (TC DATA). diff --git a/md/front-page.md b/md/front-page.md new file mode 100644 index 0000000000000000000000000000000000000000..72fa4f450005475a176a6ee7907fa8a035617ec6 --- /dev/null +++ b/md/front-page.md @@ -0,0 +1,90 @@ +::: ZA +[ETSI TS 104 176 ]{.ondemand_CHAR_size_32} V0.0.1 [(2025-10)]{.ondemand_CHAR_size_16} +::: + +![](media/TS-logo.png) + +::: ZT +Data Solutions (DATA); +::: + +::: ZT +NGSI-LD API Bindings +::: + + +::: ZT +Release # +::: + +::: ZB +***TECHNICAL SPECIFICATION*** +::: + +::: TAC +Reference + +DTS/DATA-00104176 + +Keywords + +API +ARCHITECTURE +data interoperability +Digital Twins +INTEROPERABILITY +NGSI-LD +smart agriculture +Smart Cities +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]{.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° w061004871]{.ondemand_CHAR_name_Arial_size_7} + +***Important notice*** + +The present document can be downloaded from the [ETSI Search & Browse Standards](https://www.etsi.org/standards-search) application. + +The present document may be made available in electronic versions and/or in print. The content of any electronic and/or print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI deliverable is the one made publicly available in PDF format on [ETSI deliver](http://www.etsi.org/deliver)repository. + +Users should be aware that the present document may be revised or have its status changed, this information is available in the [Milestones listing](https://portal.etsi.org/Services/editHelp/Standards-development/Tracking-a-draft/Status-codes). + +If you find errors in the present document, please send your comments to the relevant service listed under [Committee Support Staff](https://portal.etsi.org/People/Commitee-Support-Staff). + +If you find a security vulnerability in the present document, please report it through our [Coordinated Vulnerability Disclosure (CVD)](https://www.etsi.org/standards/coordinated-vulnerability-disclosure) 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. +::: + diff --git a/md/history.md b/md/history.md new file mode 100644 index 0000000000000000000000000000000000000000..9da311fd28e3d671fc2c0404a02b59098faeadc5 --- /dev/null +++ b/md/history.md @@ -0,0 +1,12 @@ +# History + +::: TAL ++:-----------------------:+:-----------------------:+:-----------------------:+ +| Document History | ++=========================+===================================================+ +| | | | ++-------------------------+-------------------------+-------------------------+ +::: + +*Latest changes made on YYYY-MM-DD* + diff --git a/md/intellectual-property-rights.md b/md/intellectual-property-rights.md new file mode 100644 index 0000000000000000000000000000000000000000..c827b5807d1d36b54d58e4354e914931cb71554e --- /dev/null +++ b/md/intellectual-property-rights.md @@ -0,0 +1,18 @@ +# Intellectual Property Rights + +::: 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/md/introduction.md b/md/introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..cf515c40f8bbf47c516b75829ad80f9d00c7a23d --- /dev/null +++ b/md/introduction.md @@ -0,0 +1,2 @@ +# Introduction + diff --git a/md/media/.gitkeep b/md/media/.gitkeep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/md/media/TS-logo.png b/md/media/TS-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..7f4cb9b83b877b2062efaae4b674cf7688d68dbd Binary files /dev/null and b/md/media/TS-logo.png differ diff --git a/md/media/image100.emf b/md/media/image100.emf new file mode 100644 index 0000000000000000000000000000000000000000..7192438d54820f19a39f7123fc9dcc585f3bdb56 Binary files /dev/null and b/md/media/image100.emf differ diff --git a/md/media/image100.png b/md/media/image100.png new file mode 100644 index 0000000000000000000000000000000000000000..0dcab61658b567995dbc660b96e54b364f035090 Binary files /dev/null and b/md/media/image100.png differ diff --git a/md/media/image101.emf b/md/media/image101.emf new file mode 100644 index 0000000000000000000000000000000000000000..d4dd47eeb91929c9fa12c61b39650bcb33612e1f Binary files /dev/null and b/md/media/image101.emf differ diff --git a/md/media/image101.png b/md/media/image101.png new file mode 100644 index 0000000000000000000000000000000000000000..0f7cbc9f3ea1649dbd39d36f5ff54417a6085f68 Binary files /dev/null and b/md/media/image101.png differ diff --git a/md/media/image102.emf b/md/media/image102.emf new file mode 100644 index 0000000000000000000000000000000000000000..475c46c69f402201e4ca638bf76a1a77dc4a2429 Binary files /dev/null and b/md/media/image102.emf differ diff --git a/md/media/image102.png b/md/media/image102.png new file mode 100644 index 0000000000000000000000000000000000000000..3ae917feb7c825fe266b3f674f4f63b4e8627fd5 Binary files /dev/null and b/md/media/image102.png differ diff --git a/md/media/image103.emf b/md/media/image103.emf new file mode 100644 index 0000000000000000000000000000000000000000..6460eed21a6de4e7ba7925c01c2f743404b68de5 Binary files /dev/null and b/md/media/image103.emf differ diff --git a/md/media/image103.png b/md/media/image103.png new file mode 100644 index 0000000000000000000000000000000000000000..3f05b9a1e2fa16fc1b285b5f4220a665799485d9 Binary files /dev/null and b/md/media/image103.png differ diff --git a/md/media/image104.emf b/md/media/image104.emf new file mode 100644 index 0000000000000000000000000000000000000000..9354cb09e57ab722f2b6766c3dd18cb69216804a Binary files /dev/null and b/md/media/image104.emf differ diff --git a/md/media/image104.png b/md/media/image104.png new file mode 100644 index 0000000000000000000000000000000000000000..53046fc47fad00e319092611c868d349a60da1e0 Binary files /dev/null and b/md/media/image104.png differ diff --git a/md/media/image105.emf b/md/media/image105.emf new file mode 100644 index 0000000000000000000000000000000000000000..f4e5f0665972392e0bc09d280edbebcd03c4b97b Binary files /dev/null and b/md/media/image105.emf differ diff --git a/md/media/image105.png b/md/media/image105.png new file mode 100644 index 0000000000000000000000000000000000000000..451be1257b1f4034a9176ade21827182198c8365 Binary files /dev/null and b/md/media/image105.png differ diff --git a/md/media/image106.emf b/md/media/image106.emf new file mode 100644 index 0000000000000000000000000000000000000000..20e311c96d0819603a0cc0dada6caa4f810699ff Binary files /dev/null and b/md/media/image106.emf differ diff --git a/md/media/image106.png b/md/media/image106.png new file mode 100644 index 0000000000000000000000000000000000000000..c25373754b4f84e6a957c953cf4f892c977f394c Binary files /dev/null and b/md/media/image106.png differ diff --git a/md/media/image107.emf b/md/media/image107.emf new file mode 100644 index 0000000000000000000000000000000000000000..ab4f81b414c5943080f497d928a16cd998329c51 Binary files /dev/null and b/md/media/image107.emf differ diff --git a/md/media/image107.png b/md/media/image107.png new file mode 100644 index 0000000000000000000000000000000000000000..aab246325f5309cb176f1c2f88751739450618fb Binary files /dev/null and b/md/media/image107.png differ diff --git a/md/media/image108.emf b/md/media/image108.emf new file mode 100644 index 0000000000000000000000000000000000000000..91b29e2beaee1bddadbe753b0cbf4b5496870ebe Binary files /dev/null and b/md/media/image108.emf differ diff --git a/md/media/image108.png b/md/media/image108.png new file mode 100644 index 0000000000000000000000000000000000000000..b9072e88470a4fbec149f6a51b470d3b60b0a118 Binary files /dev/null and b/md/media/image108.png differ diff --git a/md/media/image109.emf b/md/media/image109.emf new file mode 100644 index 0000000000000000000000000000000000000000..9ff2326b32f566db5220f3dd3fc558020ad3f66b Binary files /dev/null and b/md/media/image109.emf differ diff --git a/md/media/image109.png b/md/media/image109.png new file mode 100644 index 0000000000000000000000000000000000000000..b7bb533eb5de2710aaa91e82fe9e1e892a9c32ba Binary files /dev/null and b/md/media/image109.png differ diff --git a/md/media/image110.emf b/md/media/image110.emf new file mode 100644 index 0000000000000000000000000000000000000000..2ab099bea515cfce5929ca1ec75fbadfcefc7afd Binary files /dev/null and b/md/media/image110.emf differ diff --git a/md/media/image110.png b/md/media/image110.png new file mode 100644 index 0000000000000000000000000000000000000000..0526adbc14452f19c4a9289e979867dbb8467434 Binary files /dev/null and b/md/media/image110.png differ diff --git a/md/media/image111.emf b/md/media/image111.emf new file mode 100644 index 0000000000000000000000000000000000000000..dc0873e34ca1f0c6c691df2819ec31a2cfc55d25 Binary files /dev/null and b/md/media/image111.emf differ diff --git a/md/media/image111.png b/md/media/image111.png new file mode 100644 index 0000000000000000000000000000000000000000..20d62c496a6b1b0e207e82782678c704325592cd Binary files /dev/null and b/md/media/image111.png differ diff --git a/md/media/image112.emf b/md/media/image112.emf new file mode 100644 index 0000000000000000000000000000000000000000..d801348d7147f6c7c152bb884203b09795473bf6 Binary files /dev/null and b/md/media/image112.emf differ diff --git a/md/media/image112.png b/md/media/image112.png new file mode 100644 index 0000000000000000000000000000000000000000..309eda1f5efb164d8153a146d17c0932e80f6795 Binary files /dev/null and b/md/media/image112.png differ diff --git a/md/media/image113.emf b/md/media/image113.emf new file mode 100644 index 0000000000000000000000000000000000000000..bb7e5f43ec216a08f0b4fc79f84992f2a3f345eb Binary files /dev/null and b/md/media/image113.emf differ diff --git a/md/media/image113.png b/md/media/image113.png new file mode 100644 index 0000000000000000000000000000000000000000..b38b2607ef25d33c60a49a952d4ed2b4d2a1f1c8 Binary files /dev/null and b/md/media/image113.png differ diff --git a/md/media/image114.emf b/md/media/image114.emf new file mode 100644 index 0000000000000000000000000000000000000000..0b46fee347fde48b9687a3e60a247b0ab2a16104 Binary files /dev/null and b/md/media/image114.emf differ diff --git a/md/media/image114.png b/md/media/image114.png new file mode 100644 index 0000000000000000000000000000000000000000..f9a6517840c60c2a3baac20ef5f9555494bb23b8 Binary files /dev/null and b/md/media/image114.png differ diff --git a/md/media/image115.emf b/md/media/image115.emf new file mode 100644 index 0000000000000000000000000000000000000000..eaf90d4bc601a2593ead2b26dc8b8c8be4689014 Binary files /dev/null and b/md/media/image115.emf differ diff --git a/md/media/image115.png b/md/media/image115.png new file mode 100644 index 0000000000000000000000000000000000000000..fa82c6f6edc48041da160d1350a4a46532668003 Binary files /dev/null and b/md/media/image115.png differ diff --git a/md/media/image116.emf b/md/media/image116.emf new file mode 100644 index 0000000000000000000000000000000000000000..a2743c677b6be7420c043aaf64cab9bb75058789 Binary files /dev/null and b/md/media/image116.emf differ diff --git a/md/media/image116.png b/md/media/image116.png new file mode 100644 index 0000000000000000000000000000000000000000..885686a587163562507fd46131ef34e5ab1727f3 Binary files /dev/null and b/md/media/image116.png differ diff --git a/md/media/image117.emf b/md/media/image117.emf new file mode 100644 index 0000000000000000000000000000000000000000..cd949f30becd67abf218fbfbd0b0618fce3d1f6b Binary files /dev/null and b/md/media/image117.emf differ diff --git a/md/media/image117.png b/md/media/image117.png new file mode 100644 index 0000000000000000000000000000000000000000..c1b0cae6bb2f8113f536717769706bf5e929bd31 Binary files /dev/null and b/md/media/image117.png differ diff --git a/md/media/image118.emf b/md/media/image118.emf new file mode 100644 index 0000000000000000000000000000000000000000..b6a37066259df02c87243707f64e1c335b31c79e Binary files /dev/null and b/md/media/image118.emf differ diff --git a/md/media/image118.png b/md/media/image118.png new file mode 100644 index 0000000000000000000000000000000000000000..c42c4b785b808e0494ecd045b15bdb1bcf18b5ef Binary files /dev/null and b/md/media/image118.png differ diff --git a/md/media/image119.emf b/md/media/image119.emf new file mode 100644 index 0000000000000000000000000000000000000000..bf6a740c063721250e321093f096c822f2a038d1 Binary files /dev/null and b/md/media/image119.emf differ diff --git a/md/media/image119.png b/md/media/image119.png new file mode 100644 index 0000000000000000000000000000000000000000..93721598a7734eec1fc12116e52ec7d1b9686ce2 Binary files /dev/null and b/md/media/image119.png differ diff --git a/md/media/image120.emf b/md/media/image120.emf new file mode 100644 index 0000000000000000000000000000000000000000..a7ec9a3545a8b83fbbce807c2284cd1c10378e73 Binary files /dev/null and b/md/media/image120.emf differ diff --git a/md/media/image120.png b/md/media/image120.png new file mode 100644 index 0000000000000000000000000000000000000000..3e993fe2412566f3598a7fe16e7871f75605410f Binary files /dev/null and b/md/media/image120.png differ diff --git a/md/media/image121.emf b/md/media/image121.emf new file mode 100644 index 0000000000000000000000000000000000000000..8cc4bb20b20031447a9edcc0c6eb23417d720895 Binary files /dev/null and b/md/media/image121.emf differ diff --git a/md/media/image121.png b/md/media/image121.png new file mode 100644 index 0000000000000000000000000000000000000000..1019fb9b27592ac2eb5aecd8a7caa89652909afa Binary files /dev/null and b/md/media/image121.png differ diff --git a/md/media/image122.emf b/md/media/image122.emf new file mode 100644 index 0000000000000000000000000000000000000000..6dd06a308d7abc3708e3c50ecd07036d5d1de83d Binary files /dev/null and b/md/media/image122.emf differ diff --git a/md/media/image122.png b/md/media/image122.png new file mode 100644 index 0000000000000000000000000000000000000000..76d4cc5319ed3542a23aafbb849f10676c0d5555 Binary files /dev/null and b/md/media/image122.png differ diff --git a/md/media/image123.emf b/md/media/image123.emf new file mode 100644 index 0000000000000000000000000000000000000000..92198f4fa90822b2cea0c46a8b9d0caab518080c Binary files /dev/null and b/md/media/image123.emf differ diff --git a/md/media/image123.png b/md/media/image123.png new file mode 100644 index 0000000000000000000000000000000000000000..40c3a1699a8b68f8fb19df79b59101641f4364e6 Binary files /dev/null and b/md/media/image123.png differ diff --git a/md/media/image124.emf b/md/media/image124.emf new file mode 100644 index 0000000000000000000000000000000000000000..0f5cc8b8eb6c8f6e8998b62f402ff8326944c069 Binary files /dev/null and b/md/media/image124.emf differ diff --git a/md/media/image124.png b/md/media/image124.png new file mode 100644 index 0000000000000000000000000000000000000000..59ba45b93c65d78d44a0d59cc316d06defdceb0a Binary files /dev/null and b/md/media/image124.png differ diff --git a/md/media/image125.emf b/md/media/image125.emf new file mode 100644 index 0000000000000000000000000000000000000000..56f6f6e7259a34c16513e2e19985ff78b1155750 Binary files /dev/null and b/md/media/image125.emf differ diff --git a/md/media/image125.png b/md/media/image125.png new file mode 100644 index 0000000000000000000000000000000000000000..f74d59206bb25a04e1be4c49849029cce302512b Binary files /dev/null and b/md/media/image125.png differ diff --git a/md/media/image126.emf b/md/media/image126.emf new file mode 100644 index 0000000000000000000000000000000000000000..baa48a582ded2fe998ba0bf5818064e4109a8e84 Binary files /dev/null and b/md/media/image126.emf differ diff --git a/md/media/image126.png b/md/media/image126.png new file mode 100644 index 0000000000000000000000000000000000000000..0edf7f4577beecdd95e009c5aafc29c137419ac2 Binary files /dev/null and b/md/media/image126.png differ diff --git a/md/media/image127.emf b/md/media/image127.emf new file mode 100644 index 0000000000000000000000000000000000000000..38403991c33db50ead3cecc58cd96dc423804f6b Binary files /dev/null and b/md/media/image127.emf differ diff --git a/md/media/image127.png b/md/media/image127.png new file mode 100644 index 0000000000000000000000000000000000000000..87b2196f133bf08404412a800ebf59f343e992f2 Binary files /dev/null and b/md/media/image127.png differ diff --git a/md/media/image128.emf b/md/media/image128.emf new file mode 100644 index 0000000000000000000000000000000000000000..3241e6661f54b4b82e37a61c360195f2dadfdf72 Binary files /dev/null and b/md/media/image128.emf differ diff --git a/md/media/image128.png b/md/media/image128.png new file mode 100644 index 0000000000000000000000000000000000000000..332eebc7308d698289d5694bfff4624764b1a266 Binary files /dev/null and b/md/media/image128.png differ diff --git a/md/media/image129.emf b/md/media/image129.emf new file mode 100644 index 0000000000000000000000000000000000000000..25a662fabdb957554a6af55b3ff3c7f0906a4a81 Binary files /dev/null and b/md/media/image129.emf differ diff --git a/md/media/image129.png b/md/media/image129.png new file mode 100644 index 0000000000000000000000000000000000000000..0a4b223127d2236d55ab514434ca7aac6289a56f Binary files /dev/null and b/md/media/image129.png differ diff --git a/md/media/image130.emf b/md/media/image130.emf new file mode 100644 index 0000000000000000000000000000000000000000..1ae66d0fc880349698d89d2a13a64e2a92fe6d7f Binary files /dev/null and b/md/media/image130.emf differ diff --git a/md/media/image130.png b/md/media/image130.png new file mode 100644 index 0000000000000000000000000000000000000000..93c8da97afd95516b80c721662275fe6fa8bf715 Binary files /dev/null and b/md/media/image130.png differ diff --git a/md/media/image131.emf b/md/media/image131.emf new file mode 100644 index 0000000000000000000000000000000000000000..131e6ea4acf6412826294b4c6a464496269fb716 Binary files /dev/null and b/md/media/image131.emf differ diff --git a/md/media/image131.png b/md/media/image131.png new file mode 100644 index 0000000000000000000000000000000000000000..e1e1c3356b517eead2a41f5898d19e46cb9ac14a Binary files /dev/null and b/md/media/image131.png differ diff --git a/md/media/image132.emf b/md/media/image132.emf new file mode 100644 index 0000000000000000000000000000000000000000..736b69fb1b1066528baff0494f7e79652a0f8b8a Binary files /dev/null and b/md/media/image132.emf differ diff --git a/md/media/image132.png b/md/media/image132.png new file mode 100644 index 0000000000000000000000000000000000000000..7517986a02ff9998301caa9fc16039a33ec23e45 Binary files /dev/null and b/md/media/image132.png differ diff --git a/md/media/image133.emf b/md/media/image133.emf new file mode 100644 index 0000000000000000000000000000000000000000..3c80842eaf9875cf435f8831655adc2266de5448 Binary files /dev/null and b/md/media/image133.emf differ diff --git a/md/media/image133.png b/md/media/image133.png new file mode 100644 index 0000000000000000000000000000000000000000..35f6f85d7a686f6fd6bf1933014aa8d1f6ea002b Binary files /dev/null and b/md/media/image133.png differ diff --git a/md/media/image134.emf b/md/media/image134.emf new file mode 100644 index 0000000000000000000000000000000000000000..8c145164683540ffbc04e7853ec5077c7ad0b5cf Binary files /dev/null and b/md/media/image134.emf differ diff --git a/md/media/image134.png b/md/media/image134.png new file mode 100644 index 0000000000000000000000000000000000000000..62a841cf5cd5696fefc12b9eb019c570b1f4b814 Binary files /dev/null and b/md/media/image134.png differ diff --git a/md/media/image135.emf b/md/media/image135.emf new file mode 100644 index 0000000000000000000000000000000000000000..7155d7453ada7e47fee01794427ce1fe226b9705 Binary files /dev/null and b/md/media/image135.emf differ diff --git a/md/media/image135.png b/md/media/image135.png new file mode 100644 index 0000000000000000000000000000000000000000..356717d43f3d8842bbd2acf6c17c791bc8f5f803 Binary files /dev/null and b/md/media/image135.png differ diff --git a/md/media/image136.emf b/md/media/image136.emf new file mode 100644 index 0000000000000000000000000000000000000000..75f1dc58631137d19e5f797c58e6f62c9538c68e Binary files /dev/null and b/md/media/image136.emf differ diff --git a/md/media/image136.png b/md/media/image136.png new file mode 100644 index 0000000000000000000000000000000000000000..8a24b555cea860e0b8e0e2e3f023c69eb8b9c31d Binary files /dev/null and b/md/media/image136.png differ diff --git a/md/media/image137.emf b/md/media/image137.emf new file mode 100644 index 0000000000000000000000000000000000000000..1c295b2a274f4d1872b468714fa1d7023d3e9dac Binary files /dev/null and b/md/media/image137.emf differ diff --git a/md/media/image137.png b/md/media/image137.png new file mode 100644 index 0000000000000000000000000000000000000000..57a0a24c2a732a7d33caed9c32581c15ac30a059 Binary files /dev/null and b/md/media/image137.png differ diff --git a/md/media/image138.emf b/md/media/image138.emf new file mode 100644 index 0000000000000000000000000000000000000000..7b88b76a48b78d9cb81ddf713746a65edab6a6fd Binary files /dev/null and b/md/media/image138.emf differ diff --git a/md/media/image138.png b/md/media/image138.png new file mode 100644 index 0000000000000000000000000000000000000000..eae9acd6673d87a7a8266256e941f7d59725019a Binary files /dev/null and b/md/media/image138.png differ diff --git a/md/media/image139.emf b/md/media/image139.emf new file mode 100644 index 0000000000000000000000000000000000000000..0e54ba920c25aff3cd510d8d9859fe5a694e2e46 Binary files /dev/null and b/md/media/image139.emf differ diff --git a/md/media/image139.png b/md/media/image139.png new file mode 100644 index 0000000000000000000000000000000000000000..867a29996d6817bb76e9d01600f3414dbcc053e6 Binary files /dev/null and b/md/media/image139.png differ diff --git a/md/media/image140.emf b/md/media/image140.emf new file mode 100644 index 0000000000000000000000000000000000000000..2e105b7f3530670b7bec774837ab0fda7286033d Binary files /dev/null and b/md/media/image140.emf differ diff --git a/md/media/image140.png b/md/media/image140.png new file mode 100644 index 0000000000000000000000000000000000000000..3191adf007a8b3714fcaa8943351dce8f5de6e6b Binary files /dev/null and b/md/media/image140.png differ diff --git a/md/media/image141.emf b/md/media/image141.emf new file mode 100644 index 0000000000000000000000000000000000000000..82e96d4d5f02b06b5b07db1535e42e187889c6bb Binary files /dev/null and b/md/media/image141.emf differ diff --git a/md/media/image141.png b/md/media/image141.png new file mode 100644 index 0000000000000000000000000000000000000000..964ca425836cc2673925d0a4203229882627a13a Binary files /dev/null and b/md/media/image141.png differ diff --git a/md/media/image142.emf b/md/media/image142.emf new file mode 100644 index 0000000000000000000000000000000000000000..826310f812187de6870cf919e0d89c43abf99e2c Binary files /dev/null and b/md/media/image142.emf differ diff --git a/md/media/image142.png b/md/media/image142.png new file mode 100644 index 0000000000000000000000000000000000000000..81764e0887997ee2d10246c169ee1b9221794c8e Binary files /dev/null and b/md/media/image142.png differ diff --git a/md/media/image144.emf b/md/media/image144.emf new file mode 100644 index 0000000000000000000000000000000000000000..82f7eac7057fef1607fb9b699515b0199ca2b7de Binary files /dev/null and b/md/media/image144.emf differ diff --git a/md/media/image144.png b/md/media/image144.png new file mode 100644 index 0000000000000000000000000000000000000000..9a09447d5cbe6bc6c4b9ca2ba65dd39f785fc76c Binary files /dev/null and b/md/media/image144.png differ diff --git a/md/media/image145.png b/md/media/image145.png new file mode 100644 index 0000000000000000000000000000000000000000..c4bb4aa21be0b94a474f9aabdbdcc5cd94645f26 Binary files /dev/null and b/md/media/image145.png differ diff --git a/md/media/image146.emf b/md/media/image146.emf new file mode 100644 index 0000000000000000000000000000000000000000..ad3ad3300989f2098440f4b1534f2bbc36448aaa Binary files /dev/null and b/md/media/image146.emf differ diff --git a/md/media/image146.png b/md/media/image146.png new file mode 100644 index 0000000000000000000000000000000000000000..012371269f22a7713aca9aee74bdb08d92f5e8d6 Binary files /dev/null and b/md/media/image146.png differ diff --git a/md/media/image147.emf b/md/media/image147.emf new file mode 100644 index 0000000000000000000000000000000000000000..1aefa433edd144979d054d150b0283e0764fe20e Binary files /dev/null and b/md/media/image147.emf differ diff --git a/md/media/image147.png b/md/media/image147.png new file mode 100644 index 0000000000000000000000000000000000000000..ddc5e8aac7a8c560d5d800d088ec706f693da1b4 Binary files /dev/null and b/md/media/image147.png differ diff --git a/md/media/image148.png b/md/media/image148.png new file mode 100644 index 0000000000000000000000000000000000000000..f8bb076dc0d2c92052e7c0cb735d182abd9b04ea Binary files /dev/null and b/md/media/image148.png differ diff --git a/md/media/image78.emf b/md/media/image78.emf new file mode 100644 index 0000000000000000000000000000000000000000..3cf80fcd271e2f0b1842ab75e7edfceb71999f4d Binary files /dev/null and b/md/media/image78.emf differ diff --git a/md/media/image78.png b/md/media/image78.png new file mode 100644 index 0000000000000000000000000000000000000000..b7bd21bafe6117a90d2f000456721d80d48efa12 Binary files /dev/null and b/md/media/image78.png differ diff --git a/md/media/image79.emf b/md/media/image79.emf new file mode 100644 index 0000000000000000000000000000000000000000..a25f30962294434e5b4a67c71e6122a02da8b76a Binary files /dev/null and b/md/media/image79.emf differ diff --git a/md/media/image79.png b/md/media/image79.png new file mode 100644 index 0000000000000000000000000000000000000000..46a204e13f0a9f6a3d651e84194b87ccb9ce61a8 Binary files /dev/null and b/md/media/image79.png differ diff --git a/md/media/image80.png b/md/media/image80.png new file mode 100644 index 0000000000000000000000000000000000000000..e624f74666cbb4d4ca1edffa1f15e154d0c21ae8 Binary files /dev/null and b/md/media/image80.png differ diff --git a/md/media/image81.emf b/md/media/image81.emf new file mode 100644 index 0000000000000000000000000000000000000000..2e9ff6f3bc68c3ec810a55d7ebcaac107b9165ad Binary files /dev/null and b/md/media/image81.emf differ diff --git a/md/media/image81.png b/md/media/image81.png new file mode 100644 index 0000000000000000000000000000000000000000..5c99894ef3b2834766d303d3f8cdf8b5dfe15a51 Binary files /dev/null and b/md/media/image81.png differ diff --git a/md/media/image82.emf b/md/media/image82.emf new file mode 100644 index 0000000000000000000000000000000000000000..32ef7546042f3ed6e238ac86b898a826907af1f5 Binary files /dev/null and b/md/media/image82.emf differ diff --git a/md/media/image82.png b/md/media/image82.png new file mode 100644 index 0000000000000000000000000000000000000000..858ff2e1acedad8dcec4e9a580dcf6b4712a7e7d Binary files /dev/null and b/md/media/image82.png differ diff --git a/md/media/image83.emf b/md/media/image83.emf new file mode 100644 index 0000000000000000000000000000000000000000..65b9214f9f0e56c1416de41884bbe3b14d1c9e5b Binary files /dev/null and b/md/media/image83.emf differ diff --git a/md/media/image83.png b/md/media/image83.png new file mode 100644 index 0000000000000000000000000000000000000000..f335765b904c15d88bbf496d46609efe8b8ed5e5 Binary files /dev/null and b/md/media/image83.png differ diff --git a/md/media/image84.emf b/md/media/image84.emf new file mode 100644 index 0000000000000000000000000000000000000000..ef0e6cddbf1548d138512b6bd7cd65b5af5b6cec Binary files /dev/null and b/md/media/image84.emf differ diff --git a/md/media/image84.png b/md/media/image84.png new file mode 100644 index 0000000000000000000000000000000000000000..45885ea68283787200d4f08b0e478e514a151c21 Binary files /dev/null and b/md/media/image84.png differ diff --git a/md/media/image85.emf b/md/media/image85.emf new file mode 100644 index 0000000000000000000000000000000000000000..9d73d577d19b32974fbf556d01636ec3944facb0 Binary files /dev/null and b/md/media/image85.emf differ diff --git a/md/media/image85.png b/md/media/image85.png new file mode 100644 index 0000000000000000000000000000000000000000..fc5b82b831e4cfaa71389f0a0f0f6a72c677b68a Binary files /dev/null and b/md/media/image85.png differ diff --git a/md/media/image86.emf b/md/media/image86.emf new file mode 100644 index 0000000000000000000000000000000000000000..c9d3752555ca27b1ff9d90e17781b6783f2cbecb Binary files /dev/null and b/md/media/image86.emf differ diff --git a/md/media/image86.png b/md/media/image86.png new file mode 100644 index 0000000000000000000000000000000000000000..62dd7fbdbfd74eef6f4298c5bf38010f1874acef Binary files /dev/null and b/md/media/image86.png differ diff --git a/md/media/image87.emf b/md/media/image87.emf new file mode 100644 index 0000000000000000000000000000000000000000..b501546df6dcd9650fb92684c36ef8439b02a49e Binary files /dev/null and b/md/media/image87.emf differ diff --git a/md/media/image87.png b/md/media/image87.png new file mode 100644 index 0000000000000000000000000000000000000000..2079ad0680249bafb3ac26063b15d85c87804db7 Binary files /dev/null and b/md/media/image87.png differ diff --git a/md/media/image88.emf b/md/media/image88.emf new file mode 100644 index 0000000000000000000000000000000000000000..e95c7d5885eea56daf1ed7c9cfc275e02e5fce7b Binary files /dev/null and b/md/media/image88.emf differ diff --git a/md/media/image88.png b/md/media/image88.png new file mode 100644 index 0000000000000000000000000000000000000000..635bde1802e2b8e7178b97a8f0d9787d2fe29743 Binary files /dev/null and b/md/media/image88.png differ diff --git a/md/media/image89.emf b/md/media/image89.emf new file mode 100644 index 0000000000000000000000000000000000000000..699cf0e688630177c7eb7d07bafb533381d18959 Binary files /dev/null and b/md/media/image89.emf differ diff --git a/md/media/image89.png b/md/media/image89.png new file mode 100644 index 0000000000000000000000000000000000000000..beb0ddaab5ee43feefdb717924065b06e005754d Binary files /dev/null and b/md/media/image89.png differ diff --git a/md/media/image90.emf b/md/media/image90.emf new file mode 100644 index 0000000000000000000000000000000000000000..411b72b216bbe845dbdfe785c9a8c3471357c02e Binary files /dev/null and b/md/media/image90.emf differ diff --git a/md/media/image90.png b/md/media/image90.png new file mode 100644 index 0000000000000000000000000000000000000000..d7fac2cdad66e1a29311029d786b48084f595b36 Binary files /dev/null and b/md/media/image90.png differ diff --git a/md/media/image91.emf b/md/media/image91.emf new file mode 100644 index 0000000000000000000000000000000000000000..9d5fa9a5f758bfe50beda3727ac8da8f81b555cb Binary files /dev/null and b/md/media/image91.emf differ diff --git a/md/media/image91.png b/md/media/image91.png new file mode 100644 index 0000000000000000000000000000000000000000..943c7680044acbcc59c341d2776500672d4f2e9f Binary files /dev/null and b/md/media/image91.png differ diff --git a/md/media/image92.emf b/md/media/image92.emf new file mode 100644 index 0000000000000000000000000000000000000000..abea6cd29c27b8d2596b0b76428c7afaa400e9b2 Binary files /dev/null and b/md/media/image92.emf differ diff --git a/md/media/image92.png b/md/media/image92.png new file mode 100644 index 0000000000000000000000000000000000000000..b287f2d4527b0d843443613978de4ec4e7c71dc0 Binary files /dev/null and b/md/media/image92.png differ diff --git a/md/media/image93.emf b/md/media/image93.emf new file mode 100644 index 0000000000000000000000000000000000000000..80841c4b0e8d7bc9cebce71e462b948736ac73aa Binary files /dev/null and b/md/media/image93.emf differ diff --git a/md/media/image93.png b/md/media/image93.png new file mode 100644 index 0000000000000000000000000000000000000000..124dfbfe8a5f32334a8b39ccf41a26f40bd21a0c Binary files /dev/null and b/md/media/image93.png differ diff --git a/md/media/image94.emf b/md/media/image94.emf new file mode 100644 index 0000000000000000000000000000000000000000..0f25afb7510643b7a5e9935f2f30464e680b60e7 Binary files /dev/null and b/md/media/image94.emf differ diff --git a/md/media/image94.png b/md/media/image94.png new file mode 100644 index 0000000000000000000000000000000000000000..e5bf77bedc6a4330706c546eb1e2cfca83304cef Binary files /dev/null and b/md/media/image94.png differ diff --git a/md/media/image95.emf b/md/media/image95.emf new file mode 100644 index 0000000000000000000000000000000000000000..f613ccfb2c191ec89a923b2521f109f17a2cf00f Binary files /dev/null and b/md/media/image95.emf differ diff --git a/md/media/image95.png b/md/media/image95.png new file mode 100644 index 0000000000000000000000000000000000000000..c02f52e00758a96f6fa74da9249b7ba5b8944cd8 Binary files /dev/null and b/md/media/image95.png differ diff --git a/md/media/image96.emf b/md/media/image96.emf new file mode 100644 index 0000000000000000000000000000000000000000..79538e178d90ec332766e8b5ef42583ebb95e36c Binary files /dev/null and b/md/media/image96.emf differ diff --git a/md/media/image96.png b/md/media/image96.png new file mode 100644 index 0000000000000000000000000000000000000000..69ab11e82b7ecc101b7d134ea44eacbe35b6b7ad Binary files /dev/null and b/md/media/image96.png differ diff --git a/md/media/image97.emf b/md/media/image97.emf new file mode 100644 index 0000000000000000000000000000000000000000..a10fe6e2fef0bbdb244af6d07c621fa4963d74e8 Binary files /dev/null and b/md/media/image97.emf differ diff --git a/md/media/image97.png b/md/media/image97.png new file mode 100644 index 0000000000000000000000000000000000000000..8c835fdcfcf2040ebf61ce21cca96e03f50402a2 Binary files /dev/null and b/md/media/image97.png differ diff --git a/md/media/image98.emf b/md/media/image98.emf new file mode 100644 index 0000000000000000000000000000000000000000..6c5aa89630e430c507157d63bffc038a88a49713 Binary files /dev/null and b/md/media/image98.emf differ diff --git a/md/media/image98.png b/md/media/image98.png new file mode 100644 index 0000000000000000000000000000000000000000..aa6e3068b1d5bd03e998169eed18f7007b374754 Binary files /dev/null and b/md/media/image98.png differ diff --git a/md/media/image99.emf b/md/media/image99.emf new file mode 100644 index 0000000000000000000000000000000000000000..3ecf9657e3e37c8b0a8fff7b1ca6a676c6198bff Binary files /dev/null and b/md/media/image99.emf differ diff --git a/md/media/image99.png b/md/media/image99.png new file mode 100644 index 0000000000000000000000000000000000000000..c4479e25551a9dc58d7aaa3f4d0f43cbb35843b5 Binary files /dev/null and b/md/media/image99.png differ diff --git a/md/modal-verbs-terminology.md b/md/modal-verbs-terminology.md new file mode 100644 index 0000000000000000000000000000000000000000..e70a41f0d3a7b41538683f73059d4ed090e2ac0a --- /dev/null +++ b/md/modal-verbs-terminology.md @@ -0,0 +1,10 @@ +# Modal verbs terminology + +In the present document "**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.