diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..dbe9c82b3610ccd58d1c681848dcd322e500051e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.vscode/ \ No newline at end of file diff --git a/html/.gitkeep b/html/.gitkeep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 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..15407b6756a585ad8ed8cf934d4deef3e6becb7d --- /dev/null +++ b/md/annex-a.md @@ -0,0 +1,62 @@ +# Annex A [(normative)]{.norm}: NGSI-LD identifier considerations + +## A.1 Introduction + +The purpose of identifiers is to allow uniquely identifying NGSI-LD elements +(e.g., Entities, Context Subscriptions or [Context Source +Registrations]{.HTML-Keyboard}) within an NGSI-LD system. This annex is intended +to clarify the different issues around the design of identifiers in NGSI-LD. + +## A.2 Entity identifiers + +In order to enable the participation of NGSI-LD in linked data scenarios, all +Entities are identified by **URIs**. If those URIs are expected to participate +in external linked data relationships they **should** be dereferenceable. + +It is noteworthy that the identifier from the point of view of NGSI-LD is +different from the inherent identifier that a specific Entity may have. For +instance, an NGSI-LD Entity of Type ["Vehicle"]{.HTML-Code} may have a Property +named _`licencePlateNumber`_, which it is actually a unique identifier from the +point of view of the Entity domain, as it uniquely identifies the specific +vehicle instance. However, from the point of view of the NGSI-LD system, it may +have another identifier which might or might not include such licence plate +number identifier. + +## A.3 NGSI-LD namespace + +NGSI-LD defines a specific URN [n.23] namespace intended to help API users to +design readable, clean and simple identifiers. As it is based on URNs, the usage +of this identification approach is not recommended when dereferenceable URIs are +needed (fully-fledged linked data scenarios). + +The referred namespace is defined as follows (to be registered with IANA): + +- namespace identifier: NID = ["ngsi-ld"]{.HTML-Code} +- namespace specific string: NSS = EntityTypeName [":"]{.HTML-Code} + EntityIdentificationString + +EntityTypeName shall be an Entity Type name which can be expanded to a URI as +per the _`@context`_. + +EntityIdentificationString shall be a string that allows uniquely identifying +the subject Entity in combination with the other items being part of the NSS. + + + +>>> [!tip] EXAMPLE: + +[urn:ngsi-ld:Person:28976543]{.HTML-Code} + +>>> + + + +It is recommended that applications use this URN namespace when applicable. + +In general, the URN specification defines namespace equivalence in a +case-insensitive manner, however it is assumed that context-broker +implementations shall always use lowercase letters in namespaces where they have +a choice in case, unless there is a strong reason otherwise. Restricting the +namespace prefix to lower case [urn:ngsi-ld:]{.HTML-Code} can improve caching +and retrieval, since this ensures since alphabetic characters within the +namespace specific string are always consistent. diff --git a/md/annex-b.md b/md/annex-b.md new file mode 100644 index 0000000000000000000000000000000000000000..bf85277b9693f17b2256a6d4cb60cff184e9b645 --- /dev/null +++ b/md/annex-b.md @@ -0,0 +1,470 @@ +# Annex B [(normative)]{.norm}: Core NGSI-LD \@context definition + +Below is the definition of the Core NGSI-LD _`@context`_ which shall be +supported by implementations. + +Such definition has been tested using [i.19]. + +```json +{ + "@context": { + "@version": 1.1, + "@protected": true, + "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", + "geojson": "https://purl.org/geojson/vocab#", + "id": "@id", + "type": "@type", + "Attribute": "ngsi-ld:Attribute", + "AttributeList": "ngsi-ld:AttributeList", + "ContextSourceIdentity": "ngsi-ld:ContextSourceIdentity", + "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", + "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", + "Date": "ngsi-ld:Date", + "DateTime": "ngsi-ld:DateTime", + "EntityMap": "ngsi-ld:EntityMap", + "EntityType": "ngsi-ld:EntityType", + "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", + "EntityTypeList": "ngsi-ld:EntityTypeList", + "ExecutionResultDetails": "ngsi-ld:ExecutionResultDetails", + "Feature": "geojson:Feature", + "FeatureCollection": "geojson:FeatureCollection", + "GeoProperty": "ngsi-ld:GeoProperty", + "GeometryCollection": "geojson:GeometryCollection", + "JsonProperty": "ngsi-ld:JsonProperty", + "LanguageProperty": "ngsi-ld:LanguageProperty", + "LineString": "geojson:LineString", + "ListProperty": "ngsi-ld:ListProperty", + "ListRelationship": "ngsi-ld:ListRelationship", + "MultiLineString": "geojson:MultiLineString", + "MultiPoint": "geojson:MultiPoint", + "MultiPolygon": "geojson:MultiPolygon", + "Notification": "ngsi-ld:Notification", + "Point": "geojson:Point", + "Polygon": "geojson:Polygon", + "Property": "ngsi-ld:Property", + "Relationship": "ngsi-ld:Relationship", + "Snapshot": "ngsi-ld:Snapshot", + "SnapshotNotification": "ngsi-ld:SnapshotNotification", + "Subscription": "ngsi-ld:Subscription", + "TemporalProperty": "ngsi-ld:TemporalProperty", + "Time": "ngsi-ld:Time", + "VocabProperty": "ngsi-ld:VocabProperty", + "accept": "ngsi-ld:accept", + "aggrParams": "ngsi-ld:aggrParams", + "aggrMethods": "ngsi-ld:aggrMethods", + "aggrPeriodDuration": "ngsi-ld:aggrPeriodDuration", + "attributeCount": "attributeCount", + "attributeDetails": "attributeDetails", + "attributeList": { + "@id": "ngsi-ld:attributeList", + "@type": "@vocab" + }, + "attributeName": { + "@id": "ngsi-ld:attributeName", + "@type": "@vocab" + }, + "attributeNames": { + "@id": "ngsi-ld:attributeNames", + "@type": "@vocab" + }, + "attributeTypes": { + "@id": "ngsi-ld:attributeTypes", + "@type": "@vocab" + }, + "attributes": { + "@id": "ngsi-ld:attributes", + "@type": "@vocab" + }, + "attrs": "ngsi-ld:attrs", + "avg": { + "@id": "ngsi-ld:avg", + "@container": "@list" + }, + "bbox": { + "@container": "@list", + "@id": "geojson:bbox" + }, + "cacheDuration": "ngsi-ld:cacheDuration", + "collation": "ngsi-ld:collation", + "containedBy": "ngsi-ld:isContainedBy", + "contextSourceAlias": "ngsi-ld:contextSourceAlias", + "contextSourceExtras": { + "@id": "ngsi-ld:contextSourceExtras", + "@type": "@json" + }, + "contextSourceInfo": "ngsi-ld:contextSourceInfo", + "contextSourceTimeAt": { + "@id": "ngsi-ld:contextSourceTimeAt", + "@type": "DateTime" + }, + "contextSourceUptime": "ngsi-ld:contextSourceUptime", + "cooldown": "ngsi-ld:cooldown", + "coordinates": { + "@container": "@list", + "@id": "geojson:coordinates" + }, + "createdAt": { + "@id": "ngsi-ld:createdAt", + "@type": "DateTime" + }, + "csf": "ngsi-ld:csf", + "data": "ngsi-ld:data", + "dataset": { + "@id": "ngsi-ld:hasDataset", + "@container": "@index" + }, + "datasetId": { + "@id": "ngsi-ld:datasetId", + "@type": "@id" + }, + "deletedAt": { + "@id": "ngsi-ld:deletedAt", + "@type": "DateTime" + }, + "description": "http://purl.org/dc/terms/description", + "detail": "ngsi-ld:detail", + "distinctCount": { + "@id": "ngsi-ld:distinctCount", + "@container": "@list" + }, + "endAt": { + "@id": "ngsi-ld:endAt", + "@type": "DateTime" + }, + "endTimeAt": { + "@id": "ngsi-ld:endTimeAt", + "@type": "DateTime" + }, + "endpoint": "ngsi-ld:endpoint", + "entities": "ngsi-ld:entities", + "entity": "ngsi-ld:entity", + "entityCount": "ngsi-ld:entityCount", + "entityId": { + "@id": "ngsi-ld:entityId", + "@type": "@id" + }, + "entityList": { + "@id": "ngsi-ld:entityList", + "@container": "@list" + }, + "entityMap": { + "@id": "ngsi-ld:hasEntityMap", + "@container": "@index" + }, + "entityMapLifetime": "ngsi-ld:hasEntityMapLifetime", + "error": "ngsi-ld:error", + "errors": "ngsi-ld:errors", + "expandValues": "ngsi-ld:expandValues", + "expiresAt": { + "@id": "ngsi-ld:expiresAt", + "@type": "DateTime" + }, + "features": { + "@container": "@set", + "@id": "geojson:features" + }, + "format": "ngsi-ld:format", + "geoQ": "ngsi-ld:geoQ", + "geometry": "geojson:geometry", + "geoproperty": "ngsi-ld:geoproperty", + "georel": "ngsi-ld:georel", + "idPattern": "ngsi-ld:idPattern", + "information": "ngsi-ld:information", + "instanceId": { + "@id": "ngsi-ld:instanceId", + "@type": "@id" + }, + "isActive": "ngsi-ld:isActive", + "join": "ngsi-ld:join", + "joinLevel": "ngsi-ld:hasJoinLevel", + "json": { + "@id": "ngsi-ld:hasJSON", + "@type": "@json" + }, + "jsonKeys": "ngsi-ld:jsonKeys", + "jsonldContext": "ngsi-ld:jsonldContext", + "jsons": { + "@id": "ngsi-ld:jsons", + "@container": "@list" + }, + "key": "ngsi-ld:hasKey", + "lang": "ngsi-ld:lang", + "languageMap": { + "@id": "ngsi-ld:hasLanguageMap", + "@container": "@language" + }, + "languageMaps": { + "@id": "ngsi-ld:hasLanguageMaps", + "@container": "@list" + }, + "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString", + "lastFailure": { + "@id": "ngsi-ld:lastFailure", + "@type": "DateTime" + }, + "lastN": "ngsi-ld:lastN", + "lastNotification": { + "@id": "ngsi-ld:lastNotification", + "@type": "DateTime" + }, + "lastSuccess": { + "@id": "ngsi-ld:lastSuccess", + "@type": "DateTime" + }, + "lastUsedAt": { + "@id": "ngsi-ld:lastUsedAt", + "@type": "DateTime" + }, + "linkedMaps": "ngsi-ld:linkedMaps", + "localOnly": "ngsi-ld:localOnly", + "location": "ngsi-ld:location", + "management": "ngsi-ld:management", + "managementInterval": "ngsi-ld:managementInterval", + "max": { + "@id": "ngsi-ld:max", + "@container": "@list" + }, + "min": { + "@id": "ngsi-ld:min", + "@container": "@list" + }, + "mode": "ngsi-ld:mode", + "modifiedAt": { + "@id": "ngsi-ld:modifiedAt", + "@type": "DateTime" + }, + "ngsildproof": { + "@id": "ngsi-ld:ngsildproof", + "@context": [ + { + "entityIdSealed": "ngsi-ld:entityIdSealed", + "entityTypeSealed": { + "@id": "ngsi-ld:entityTypeSealed", + "@type": "@vocab" + } + }, + "https://w3id.org/security/data-integrity/v2" + ] + }, + "ngsildConformance": "ngsi-ld:ngsildConformance", + "notification": "ngsi-ld:notification", + "notificationTrigger": "ngsi-ld:notificationTrigger", + "notifiedAt": { + "@id": "ngsi-ld:notifiedAt", + "@type": "DateTime" + }, + "notifierInfo": "ngsi-ld:notifierInfo", + "notUpdated": "ngsi-ld:notUpdated", + "object": { + "@id": "ngsi-ld:hasObject", + "@type": "@id" + }, + "objectList": { + "@id": "ngsi-ld:hasObjectList", + "@container": "@list" + }, + "objectLists": { + "@id": "ngsi-ld:hasObjectLists", + "@container": "@list" + }, + "objects": { + "@id": "ngsi-ld:hasObjects", + "@container": "@list" + }, + "objectType": { + "@id": "ngsi-ld:hasObjectType", + "@type": "@vocab" + }, + "observationInterval": "ngsi-ld:observationInterval", + "observationSpace": "ngsi-ld:observationSpace", + "observedAt": { + "@id": "ngsi-ld:observedAt", + "@type": "DateTime" + }, + "omit": "ngsi-ld:omit", + "operations": "ngsi-ld:operations", + "operationSpace": "ngsi-ld:operationSpace", + "orderBy": { + "@container": "@list", + "@id": "ngsi-ld:orderBy" + }, + "ordering": "ngsi-ld:ordering", + "pick": "ngsi-ld:pick", + "previousJson": { + "@id": "ngsi-ld:hasPreviousJson", + "@type": "@json" + }, + "previousLanguageMap": { + "@id": "ngsi-ld:hasPreviousLanguageMap", + "@container": "@language" + }, + "previousObject": { + "@id": "ngsi-ld:hasPreviousObject", + "@type": "@id" + }, + "previousObjectList": { + "@id": "ngsi-ld:hasPreviousObjectList", + "@container": "@list" + }, + "previousValue": "ngsi-ld:hasPreviousValue", + "previousValueList": { + "@id": "ngsi-ld:hasPreviousValueList", + "@container": "@list" + }, + "previousVocab": { + "@id": "ngsi-ld:hasPreviousVocab", + "@type": "@vocab" + }, + "problemDetails": { + "@id": "ngsi-ld:problemDetails", + "@type": "@json" + }, + "properties": "geojson:properties", + "propertyNames": { + "@id": "ngsi-ld:propertyNames", + "@type": "@vocab" + }, + "q": "ngsi-ld:q", + "reason": "ngsi-ld:reason", + "receiverInfo": "ngsi-ld:receiverInfo", + "refreshRate": "ngsi-ld:refreshRate", + "registrationId": "ngsi-ld:registrationId", + "registrationName": "ngsi-ld:registrationName", + "relationshipNames": { + "@id": "ngsi-ld:relationshipNames", + "@type": "@vocab" + }, + "resultStatus": "ngsi-ld:resultStatus", + "scope": "ngsi-ld:scope", + "scopeQ": "ngsi-ld:scopeQ", + "showChanges": "ngsi-ld:showChanges", + "snapshotId": "ngsi-ld:snapshotId", + "snapshotLifetime": "ngsi-ld:snapshotLifetime", + "snapshotPriority": "ngsi-ld:snapshotPriority", + "snapshotQueries": { + "@id": "ngsi-ld:snapshotQueries", + "@container": "@list" + }, + "snapshotQueriesDetails": { + "@id": "ngsi-ld:snapshotQueriesDetails", + "@container": "@list" + }, + "snapshotStatus": "ngsi-ld:snapshotStatus", + "snapshotTemporalQueries": { + "@id": "ngsi-ld:snapshotTemporalQueries", + "@container": "@list" + }, + "snapshotTemporalQueriesDetails": { + "@id": "ngsi-ld:snapshotTemporalQueriesDetails", + "@container": "@list" + }, + "splitEntities": "ngsi-ld:hasSplitEntities", + "startAt": { + "@id": "ngsi-ld:startAt", + "@type": "DateTime" + }, + "status": "ngsi-ld:status", + "stddev": { + "@id": "ngsi-ld:stddev", + "@container": "@list" + }, + "subscriptionId": { + "@id": "ngsi-ld:subscriptionId", + "@type": "@id" + }, + "subscriptionName": "ngsi-ld:subscriptionName", + "success": { + "@id": "ngsi-ld:success", + "@type": "@id" + }, + "sum": { + "@id": "ngsi-ld:sum", + "@container": "@list" + }, + "sumsq": { + "@id": "ngsi-ld:sumsq", + "@container": "@list" + }, + "sysAttrs": "ngsi-ld:sysAttrs", + "temporalQ": "ngsi-ld:temporalQ", + "tenant": { + "@id": "ngsi-ld:tenant", + "@type": "@id" + }, + "throttling": "ngsi-ld:throttling", + "timeAt": { + "@id": "ngsi-ld:timeAt", + "@type": "DateTime" + }, + "timeInterval": "ngsi-ld:timeInterval", + "timeout": "ngsi-ld:timeout", + "timeproperty": "ngsi-ld:timeproperty", + "timerel": "ngsi-ld:timerel", + "timesFailed": "ngsi-ld:timesFailed", + "timesSent": "ngsi-ld:timesSent", + "title": "http://purl.org/dc/terms/title", + "totalCount": { + "@id": "ngsi-ld:totalCount", + "@container": "@list" + }, + "triggerReason": "ngsi-ld:triggerReason", + "typeList": { + "@id": "ngsi-ld:typeList", + "@type": "@vocab" + }, + "typeName": { + "@id": "ngsi-ld:typeName", + "@type": "@vocab" + }, + "typeNames": { + "@id": "ngsi-ld:typeNames", + "@type": "@vocab" + }, + "unchanged": "ngsi-ld:unchanged", + "unitCode": "ngsi-ld:unitCode", + "updated": "ngsi-ld:updated", + "uri": "ngsi-ld:uri", + "value": "ngsi-ld:hasValue", + "valueList": { + "@id": "ngsi-ld:hasValueList", + "@container": "@list" + }, + "valueLists": { + "@id": "ngsi-ld:hasValueLists", + "@container": "@list" + }, + "values": { + "@id": "ngsi-ld:hasValues", + "@container": "@list" + }, + "valueType": { + "@id": "ngsi-ld:hasValueType", + "@type": "@vocab" + }, + "vocab": { + "@id": "ngsi-ld:hasVocab", + "@type": "@vocab" + }, + "vocabs": { + "@id": "ngsi-ld:hasVocabs", + "@container": "@list" + }, + "watchedAttributes": { + "@id": "ngsi-ld:watchedAttributes", + "@type": "@vocab" + }, + "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" + } +} +``` + + + +>>> [!note] NOTE: + +Implementers can take advantage of prefixed terms, i.e. in the form +ngsi-ld:term, to provide a terser representation of the Core _`@context`_. + +>>> + + diff --git a/md/annex-bibliography.md b/md/annex-bibliography.md new file mode 100644 index 0000000000000000000000000000000000000000..5043c9d24027419353136852dacc8b5e2708c126 --- /dev/null +++ b/md/annex-bibliography.md @@ -0,0 +1,3 @@ +# Annex [(informative)]{.inform}: Bibliography + +- diff --git a/md/annex-c.md b/md/annex-c.md new file mode 100644 index 0000000000000000000000000000000000000000..46b56cb6ab31d0b9a19528b9c5aff9856a6576f8 --- /dev/null +++ b/md/annex-c.md @@ -0,0 +1,2280 @@ +# Annex C [(informative)]{.inform}: Examples of using the API + +## C.1 Introduction + +This annex is informative and is intended to show in action the JSON-LD +representation defined by NGSI-LD. + +JSON representations of the examples shown in this annex can be found at [i.20]. + +## C.2 Entity representation + +### C.2.1 Property graph + +Figure+++below shows a diagram representing a property graph to be used for the +examples discussed in this clause. + + + +::: FL + +::: + +::: TF +Figure: Reference example +::: + + + +As per the algorithms described above and as per the rules for generating the +JSON-LD representation of NGSI-LD entities the above graph will result in the +following JSON-LD representations. The syntax has been checked using the JSON-LD +Playground tool [i.21]. + +### C.2.2 Vehicle Entity + +#### C.2.2.1 Normalized representation + +##### C.2.2.1.1 Normalized representation + +The normalized representation is a lossless representation of an Entity, where +every _Property_ is defined by a _`type`_ and a _`value`_ and every +_Relationship_ is defined by a _`type`_ and an _`object`_. + +Below there is a representation of an Entity of Type ["Vehicle"]{.HTML-Code}. It +can be observed that the _`@context`_ is composed of different parts, namely the +Core _`@context`_ and several vocabulary-specific _`@contexts`_. + +It is noteworthy that the _`@context`_ corresponding to the Parking domain is +included as it is referenced through the _`isParked`_ Relationship. + +```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", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "objectType": "OffStreetParking", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "type": "VocabProperty", + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "type": "ListProperty", + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "type": "Relationship", + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + }, + "route": { + "type": "ListRelationship", + "objectType": "City", + "objectList": [ + { "object": "urn:ngsi-ld:City:Antwerp" }, + { "object": "urn:ngsi-ld:City:Rotterdam" }, + { "object": "urn:ngsi-ld:City:Amsterdam" } + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +##### C.2.2.1.2 Normalized representation when inline Linked Entity retrieval is used + +When inline [Linked Entity]{.HTML-Keyboard} retrieval (see clause 7.7.2) is +specified, any _Relationships_ which target Entities stored locally or include +an _`objectType`_ Attribute are returned in an expanded format. Attributes of +["type": "Relationship"]{.HTML-Code} are returned with an additional _`entity`_ +sub-Attribute, which holds the normalized [Linked Entity]{.HTML-Keyboard} data +corresponding to the _Relationship's_ target _`object`_ URI. Attributes of +["type": "ListRelationship"]{.HTML-Code} are returned with an additional +_`entityList`_ sub-Attribute which in turn holds an ordered array of the +normalized [Linked Entities]{.HTML-Keyboard} corresponding to the target +"objectList" URIs. + +```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", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "objectType": "OffStreetParking", + "entity": { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": { + "value": "Top Parking", + "type": "Property" + }, + "operatedBy": { + "object": "urn:ngsi-ld:Company:BigParkingCorp", + "type": "Relationship" + } + }, + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "type": "VocabProperty", + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "type": "ListProperty", + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "type": "Relationship", + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], + "entity": [ + { + "id": "urn:ngsi-ld:Person:Alice", + "type": "Person", + "name": { + "value": "Alice", + "type": "Property" + } + }, + { + "id": "urn:ngsi-ld:Person:Bob", + "type": "Person", + "name": { + "value": "Bob", + "type": "Property" + } + } + ] + }, + "route": { + "type": "ListRelationship", + "objectType": "City", + "objectList": [ + { "object": "urn:ngsi-ld:City:Antwerp" }, + { "object": "urn:ngsi-ld:City:Rotterdam" }, + { "object": "urn:ngsi-ld:City:Amsterdam" } + ], + "entityList": [ + { + "id": "urn:ngsi-ld:City:Antwerp", + "type": "City", + "name": { + "value": "Antwerp", + "type": "Property" + } + }, + { + "id": "urn:ngsi-ld:City:Rotterdam", + "type": "City", + "name": { + "value": "Rotterdam", + "type": "Property" + } + }, + { + "id": "urn:ngsi-ld:City:Amsterdam", + "type": "City", + "name": { + "value": "Amsterdam", + "type": "Property" + } + } + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +##### C.2.2.1.3 Normalized representation when flattened Linked Entity retrieval is used + +When flattened [Linked Entity]{.HTML-Keyboard} retrieval (see clause 7.7.3) is +specified, an array of normalized Entities is returned. Whenever a +_Relationship_ Attribute targets an Entity stored locally or includes an +_`objectType`_, an additional normalized [Linked Entity]{.HTML-Keyboard} holding +data corresponding to the _Relationship's_ target _`object`_ URI is appended to +the array. For Attributes of type ["ListRelationship"]{.HTML-Code}, an array of +normalized [Linked Entities]{.HTML-Keyboard} is appended, which hold the data +corresponding to each of the target URIs found within its _`objectList`_. + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": { + "type": "Property", + "value": "Mercedes" + }, + "street": { + "type": "LanguageProperty", + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "type": "Relationship", + "objectType": "OffStreetParking", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "type": "VocabProperty", + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "type": "ListProperty", + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "type": "Relationship", + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + }, + "route": { + "type": "ListRelationship", + "objectType": "City", + "objectList": [ + { "object": "urn:ngsi-ld:City:Antwerp" }, + { "object": "urn:ngsi-ld:City:Rotterdam" }, + { "object": "urn:ngsi-ld:City:Amsterdam" } + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": { + "value": "Top Parking", + "type": "Property" + }, + "operatedBy": { + "object": "urn:ngsi-ld:Company:BigParkingCorp", + "type": "Relationship" + }, + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:Person:Alice", + "type": "Person", + "name": { + "value": "Alice", + "type": "Property" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:Person:Bob", + "type": "Person", + "name": { + "value": "Bob", + "type": "Property" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:City:Antwerp", + "type": "City", + "name": { + "value": "Antwerp", + "type": "Property" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:City:Rotterdam", + "type": "City", + "name": { + "value": "Rotterdam", + "type": "Property" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:City:Amsterdam", + "type": "City", + "name": { + "value": "Amsterdam", + "type": "Property" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +] +``` + +##### C.2.2.1.4 Normalized representation when language filter is used + +When the Language Filter (see clause 7.2.7) is used, Properties of type +["LanguageProperty"]{.HTML-Code} are returned as type ["Property",]{.HTML-Code} +and their _`languageMap`_ are reduced to simple strings. For example if the +language filter [lang=fr]{.HTML-Code} is specified, only the value for French +language is present. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": { + "type": "Property", + "value": "Mercedes" + }, + "street": { + "type": "Property", + "value": "Grand Place", + "lang": "fr" + }, + "isParked": { + "type": "Relationship", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "type": "VocabProperty", + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "type": "ListProperty", + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "type": "Relationship", + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + }, + "route": { + "type": "ListRelationship", + "objectType": "City", + "objectList": [ + { "object": "urn:ngsi-ld:City:Antwerp" }, + { "object": "urn:ngsi-ld:City:Rotterdam" }, + { "object": "urn:ngsi-ld:City:Amsterdam" } + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.2.2 Concise representation + +##### C.2.2.2.1 Concise representation + +The concise representation is a terser, lossless form of the normalized +representation, where redundant Attribute _`type`_ members are omitted and the +following rules are applied: + +- Every _Property_ without further sub-attributes is represented directly by the + _Property_ value only. +- Every _Property_ that includes further sub-attributes is represented by a + value key-value pair. +- Every _GeoProperty_ without further sub-attributes is represented by the + _GeoProperty's_ GeoJSON representation only. +- Every _GeoProperty_ that includes further sub-attributes is represented by a + value key-value pair. +- Every _LanguageProperty_ is represented by a _`languageMap`_ key-value pair. +- Every _ListProperty_ is represented directly by the array of _Property_ + values. +- Every _JsonProperty_ is represented by a _`json`_ the value of which is raw + JSON which is not available for JSON-LD representation. +- Every _VocabProperty_ is represented by a _`vocab`_ the value of which is a + compacted URI. +- Every _Relationship_ is represented by an object key-value pair. +- Every _ListRelationship_ is represented by an array of URIs. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "objectType": "OffStreetParking", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + }, + "route": { + "objectType": "City", + "objectList": [ + "urn:ngsi-ld:City:Antwerp", + "urn:ngsi-ld:City:Rotterdam", + "urn:ngsi-ld:City:Amsterdam" + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +##### C.2.2.2.2 Concise representation when inline Linked Entity retrieval is used + +When inline [Linked Entity]{.HTML-Keyboard} retrieval (see clause 7.7.2) is +specified, any _Relationships_ which target Entities stored locally or include +an _`objectType`_ Attribute are returned in an expanded format. The concise +[Linked Entity]{.HTML-Keyboard} data corresponding to the _Relationship's_ +target _`object`_ URI is returned within an _`entity`_ sub-Attribute. Attributes +of type ["ListRelationship"]{.HTML-Code} are returned within an _`entityList`_ +sub-Attribute which in turn holds an ordered array of the [Linked +Entities]{.HTML-Keyboard} in the concise format corresponding to each of the +target*`objectList`* URIs. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "objectType": "OffStreetParking", + "entity": { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": "Top Parking", + "operatedBy": { + "object": "urn:ngsi-ld:Company:BigParkingCorp" + } + }, + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], + "entity": [ + { + "id": "urn:ngsi-ld:Person:Alice", + "type": "Person", + "name": "Alice" + }, + { + "id": "urn:ngsi-ld:Person:Bob", + "type": "Person", + "name": "Bob" + } + ] + }, + "route": { + "objectType": "City", + "objectList": [ + "urn:ngsi-ld:City:Antwerp", + "urn:ngsi-ld:City:Rotterdam", + "urn:ngsi-ld:City:Amsterdam" + ], + "entityList": [ + { + "id": "urn:ngsi-ld:City:Antwerp", + "type": "City", + "name": " Antwerp" + }, + { + "id": "urn:ngsi-ld:City:Rotterdam", + "type": "City", + "name": "Rotterdam" + }, + { + "id": "urn:ngsi-ld:City:Amsterdam", + "type": "City", + "name": "Amsterdam" + } + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +##### C.2.2.2.3 Concise representation when flattened Linked Entity retrieval is used + +When flattened [Linked Entity]{.HTML-Keyboard} retrieval (see clause 7.7.3) is +specified, an array of concise Entities is returned. Whenever a _Relationship_ +Attribute targets an Entity stored locally or includes an _`objectType`_, an +additional concise [Linked Entity]{.HTML-Keyboard} holding data corresponding to +the _Relationship's_ target _`object`_ URI is appended to the response. For +Attributes of type ["ListRelationship"]{.HTML-Code}, an array of concise [Linked +Entities]{.HTML-Keyboard} is appended to the response which hold the data +corresponding to each of the target URIs found within its _`objectList`_. + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "objectType": "OffStreetParking", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + }, + "route": { + "objectType": "City", + "objectList": [ + "urn:ngsi-ld:City:Antwerp", + "urn:ngsi-ld:City:Rotterdam", + "urn:ngsi-ld:City:Amsterdam" + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": "Top Parking", + "operatedBy": { + "object": "urn:ngsi-ld:Company:BigParkingCorp" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": " urn:ngsi-ld:Person:Alice", + "type": "Person", + "name": "Alice", + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": " urn:ngsi-ld:Person:Bob", + "type": "Person", + "name": "Bob", + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:City:Antwerp", + "type": "City", + "name": " Antwerp", + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:City:Rotterdam", + "type": "City", + "name": "Rotterdam", + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:City:Amsterdam", + "type": "City", + "name": "Amsterdam", + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +] +``` + +##### C.2.2.2.4 Concise representation when Language Filter is used + +The rules apply as defined in the previous examples. For example if the language +filter [lang=fr]{.HTML-Code} is specified. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "value": "Grand Place", + "lang": "fr" + }, + "isParked": { + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "objectType": "OffStreetParking", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "objectType": "Person", + "objectList": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + }, + "route": { + "objectType": "City", + "objectList": [ + "urn:ngsi-ld:City:Antwerp", + "urn:ngsi-ld:City:Rotterdam", + "urn:ngsi-ld:City:Amsterdam" + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.2.3 Simplified representation + +##### C.2.2.3.1 Simplified representation + +The simplified representation is a collapsed, lossy representation of an Entity, +which focuses on Property Values and Relationship objects present at the first +level of the graph only. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": [300, 300, 120, 6], + "passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], + "route": [ + "urn:ngsi-ld:City:Antwerp", + "urn:ngsi-ld:City:Rotterdam", + "urn:ngsi-ld:City:Amsterdam" + ], + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +##### C.2.2.3.2 Simplified representation when inline Linked Entity retrieval is used + +When inline [Linked Entity]{.HTML-Keyboard} retrieval (see clause 7.7.2) is +specified, any _Relationships_ which target Entities stored locally or include +an _`objectType`_ Attribute are returned as a JSON object holding key-value +pairs corresponding to the data from the _Relationship's_ target _`object`_ URI +in simplified format. Attributes of type ["ListRelationship"]{.HTML-Code} are +returned as array of JSON objects each holding key-value pairs corresponding to +the data obtained from the target _`objectList`_ URIs. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": "Top Parking", + "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" + }, + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": [300, 300, 120, 6], + "passengers": [ + { + "id": "urn:ngsi-ld:Person:Alice", + "type": "Person", + "name": "Alice" + }, + { + "id": "urn:ngsi-ld:Person:Bob", + "type": "Person", + "name": "Bob" + } + ], + "route": [ + { + "id": "urn:ngsi-ld:City:Antwerp", + "type": "City", + "name": "Antwerp" + }, + { + "id": "urn:ngsi-ld:City:Rotterdam", + "type": "City", + "name": "Rotterdam" + }, + { + "id": "urn:ngsi-ld:City:Amsterdam", + "type": "City", + "name": "Amsterdam" + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +##### C.2.2.3.3 Simplified representation when flattened Linked Entity retrieval is used + +When flattened [Linked Entity]{.HTML-Keyboard} retrieval (see clause 7.7.3) is +specified, an array of JSON Objects is returned. Whenever a _Relationship_ +Attribute targets an Entity stored locally or includes an _`objectType`_, an +additional JSON Object of key-value pairs holding data corresponding to the +_Relationship's_ target _`object`_ URI is appended to the response. For +Attributes of type ["ListRelationship"]{.HTML-Code}, an array of JSON Objects +each holding key-value pairs corresponding to the data obtained from the target +_`objectList`_ URIs is appended to the response. + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": [300, 300, 120, 6], + "passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], + "route": [ + "urn:ngsi-ld:City:Antwerp", + "urn:ngsi-ld:City:Rotterdam", + "urn:ngsi-ld:City:Amsterdam" + ], + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": " OffStreetParking", + "name": "Top Parking", + "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" + }, + { + "id": "urn:ngsi-ld:Person:Alice", + "type": "Person", + "name": "Alice" + }, + { + "id": "urn:ngsi-ld:Person:Bob", + "type": "Person", + "name": "Bob" + }, + { + "id": "urn:ngsi-ld:City:Antwerp", + "type": "City", + "name": " Antwerp" + }, + { + "id": "urn:ngsi-ld:City:Rotterdam", + "type": "City", + "name": "Rotterdam" + }, + { + "id": "urn:ngsi-ld:City:Amsterdam", + "type": "City", + "name": "Amsterdam" + } +] +``` + +##### C.2.2.3.4 Simplified representation of natural language Attributes + +The simplified natural language representation is a collapsed representation of +an Entity, which focuses on Property Values and Relationship objects present at +the first level of the graph, and where _`languageMap`_ are reduced to simple +string properties. For example if the language filter [lang=fr]{.HTML-Code} is +specified. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": "Grand Place", + "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", + "category": { + "vocab": "non-commercial" + }, + "tyreTreadDepths": [300, 300, 120, 6], + "passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], + "route": [ + "urn:ngsi-ld:City:Antwerp", + "urn:ngsi-ld:City:Rotterdam", + "urn:ngsi-ld:City:Amsterdam" + ], + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.2.4 Multi-Attribute + +##### C.2.2.4.1 Normalized multi-Attribute example + +Below is an example, where the speed of the car is provided by two different +sources. As both may be relevant at the same time, there are two individual +attribute instances for speed; each is identified by a _`datasetId`_ and both +instances are represented in an array. The _`datasetId`_ enables individually +creating, updating and deleting a particular instance without affecting the +instance from another source + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "value": 55, + "source": { + "type": "Property", + "value": "Speedometer" + }, + "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" + }, + { + "type": "Property", + "value": 54.5, + "source": { + "type": "Property", + "value": "GPS" + }, + "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" + } + ], + "@context": [ + { + "Vehicle": "http://example.org/Vehicle", + "speed": "http://example.org/speed", + "source": "http://example.org/hasSource" + }, + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +##### C.2.2.4.2 Simplified multi-Attribute example + +The simplified representation is a collapsed, lossy representation of an Entity, +which focuses on Property Values and Relationship objects present at the first +level of the graph only. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "speed": { + "dataset": { + "urn:ngsi-ld:Property:speedometerA4567-speed": 55, + "urn:ngsi-ld:Property:gpsBxyz123-speed": 54.5 + } + }, + "@context": [ + { + "Vehicle": "http://example.org/Vehicle", + "speed": "http://example.org/speed" + }, + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +### C.2.3 Parking Entity + +#### C.2.3.1 Normalized representation + +The normalized representation is a lossless representation of an Entity, where +every _Property_ is defined by a _`type`_ and a _`value`_ and every +_Relationship_ is defined by a _`type`_ and an _`object`_. + +Below there is a representation of an Entity of Type +["OffStreetParking"]{.HTML-Code}. It can be observed that the _`@context`_ is +composed of two different elements, the Core one and the vocabulary-specific +one. + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.5, 41.2] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.3.2 Concise represenatation + +The concise representation is a terser, lossless form of the normalized +representation, where redundant Attribute _`type`_ members are omitted and the +following rules are applied: + +- Every _Property_ without further sub-attributes is represented by the + _Property_ value only. +- Every _Property_ that includes further sub-attributes is represented by a + value key-value pair. +- Every _GeoProperty_ without further sub-attributes is represented by the + _GeoProperty's_ GeoJSON representation only. +- Every _GeoProperty_ that includes further sub-attributes is represented by a + value key-value pair. +- Every _LanguageProperty_ is defined by a _`languageMap`_ key-value pair. +- Every _VocabProperty_ is represented by a _`vocab`_ the value of which is a + compacted URI. +- Every _Relationship_ is defined by an object key-value pair. + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": { + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.7, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.5, 41.2] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.3.3 Simplified representation + +The Simplified Representation (also known as ["keyValues"]{.HTML-Code}) is a +lossy, collapsed representation of an Entity, which focuses on Property Values +and Relationship objects present at the first level of the graph only. + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": 121, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.5, 41.2] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.3.4 Normalized GeoJSON representation + +The normalized GeoJSON representation of a single Entity is defined as a single +GeoJSON _Feature_ object as follows: + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +} +``` + +The GeoJSON representation of multiple Entities is defined as a GeoJSON +_FeatureCollection_ object containing an array of GeoJSON features corresponding +to the individual Entity representations. + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.5, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown2", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown Two" + }, + "availableSpotNumber": { + "type": "Property", + "value": 99, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.8 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C2" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 100 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.3.5 Concise GeoJSON representation + +The concise GeoJSON representation of a single Entity is defined as a single +GeoJSON _Feature_ object as follows: + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": { + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.7, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "totalSpotNumber": 200, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +} +``` + +The concise GeoJSON representation of multiple Entities is defined as a GeoJSON +_FeatureCollection_ object containing an array of GeoJSON features corresponding +to the individual Entity representations in concise GeoJSON format. + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.5, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": { + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.7, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown2", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown Two", + "availableSpotNumber": { + "value": 99, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.8, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C2" + } + }, + "totalSpotNumber": 100, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +#### C.2.3.6 Simplified GeoJSON representation + +The simplified GeoJSON representation of a single Entity is defined as a single +GeoJSON _Feature_ object where the properties represent a collapsed +representation of the Entity, which focuses on Property Values and Relationship +objects present at the first level of the graph. + +```json +{ + "id": "urn:ngsi-ld:offstreetparking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": 121, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +The simplified GeoJSON representation of multiple Entities is defined as a +GeoJSON _FeatureCollection_ object containing an array of GeoJSON features +corresponding to the individual Entity representations in simplified GeoJSON +format. + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.5, 41.2] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": 121, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.5, 41.2] + } + } + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown2", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown Two", + "availableSpotNumber": 99, + "totalSpotNumber": 100, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +### C.2.4 \@context + +The disposition of the _`@context`_ can be as an inline JSON object, as a +dereferenceable URI or as a (multiple) combination of both. In the examples +above the _`@context`_ is provided through several dereferenceable URIs. The +resulting _`@context`_ (obtained by merging the content of the resource +referenced by the referred URIs) is shown below. + + + +>>> [!note] NOTE 1: + +For brevity reasons the _`@context`_ does not contain the API terms defined by clause 5.2.6. + +>>> + + + + + +>>> [!note] NOTE 2: + +Some extra terms are defined because they will be used in examples later presented. + +>>> + + + +```json +{ + "id": "@id", + "type": "@type", + "Property": "https://uri.etsi.org/ngsi-ld/Property", + "Relationship": "https://uri.etsi.org/ngsi-ld/Relationship", + "value": "https://uri.etsi.org/ngsi-ld/hasValue", + "object": { + "@type": "@id", + "@id": "https://uri.etsi.org/ngsi-ld/hasObject" + }, + "observedAt": { + "@type": "https://uri.etsi.org/ngsi-ld/DateTime", + "@id": "https://uri.etsi.org/ngsi-ld/observedAt" + }, + "datasetId": { + "@id": "https://uri.etsi.org/ngsi-ld/datasetId", + "@type": "@id" + }, + "location": "https://uri.etsi.org/ngsi-ld/location", + "GeoProperty": "https://uri.etsi.org/ngsi-ld/GeoProperty", + "Vehicle": "http://example.org/vehicle/Vehicle", + "street": "http://example.org/vehicle/street", + "brandName": "http://example.org/vehicle/brandName", + "category": "http://example.org/vehicle/category", + "tyreTreadDepths": "http://example.org/vehicle/tyreTreadDepths", + "passengers": "http://example.org/vehicle/passengers", + "speed": "http://example.org/vehicle/speed", + "isParked": { + "@type": "@id", + "@id": "http://example.org/common/isParked" + }, + "OffStreetParking": "http://example.org/parking/OffStreetParking", + "availableSpotNumber": "http://example.org/parking/availableSpotNumber", + "totalSpotNumber": "http://example.org/parking/totalSpotNumber", + "isNextToBuilding": { + "@type": "@id", + "@id": "http://example.org/common/isNextToBuilding" + }, + "reliability": "http://example.org/common/reliability", + "providedBy": { + "@type": "@id", + "@id": "http://example.org/common/providedBy" + }, + "name": "http://example.org/common/name", + "commercial": "http://example.org/vehicle/commercial", + "non-commercial": "http://example.org/vehicle/non-commercial", + "Integer": "http://www.w3.org/2001/XMLSchema#Integer" +} +``` + +## C.3 Context Source Registration + +Below there is an example representation of a [Context Source +Registration]{.HTML-Keyboard}. It makes use of the _`@context`_ formerly +described. + +```json +{ + "id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456", + "type": "ContextSourceRegistration", + "information": [ + { + "entities": [ + { + "id": "urn:ngsi-ld:Vehicle:A456", + "type": "Vehicle" + } + ], + "propertyNames": ["brandName", "speed"], + "relationshipNames": ["isParked"] + }, + { + "entities": [ + { + "idPattern": ".*downtown$", + "type": "OffStreetParking" + }, + { + "idPattern": ".*47$", + "type": "OffStreetParking" + } + ], + "propertyNames": ["availableSpotNumber", "totalSpotNumber"], + "relationshipNames": ["isNextToBuilding"] + } + ], + "endpoint": "http://my.csource.org:1026", + "location": { + "type": "Polygon", + "coordinates": [ + [100, 0], + [101, 0], + [101, 1], + [100, 1], + [100, 0] + ] + }, + "managementInterval": { + "startAt": " 2017-11-29T14:53:15Z" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +The Registration is referring to a Temporal [Context Source]{.HTML-Keyboard} +capable of providing temporal information from Entities of type +["Vehicle"]{.HTML-Code} and ["OffStreetParking"]{.HTML-Code}, meeting certain id +requirements. More concretely, it can only provide the referenced Properties and +Relationships. Temporal information is provided for the given +_`managementInterval`_, i.e. related to _`createdAt`_ and _`modifiedAt`_ +Temporal Properties. The _`managementInterval`_ is specified as an open +interval, so only a starting point is given. In addition, the Registration +example covers a particular geographical area. + +## C.4 Context Subscription + +Below there is an example of a Context Subscription. It makes use of the +_`@context`_ formerly described. + +```json +{ + "id": "urn:ngsi-ld:Subscription:mySubscription", + "type": "Subscription", + "entities": [ + { + "type": "Vehicle" + } + ], + "watchedAttributes": ["speed"], + "q": "speed>50", + "geoQ": { + "georel": "near;maxDistance==2000", + "geometry": "Point", + "coordinates": [-1, 100] + }, + "notification": { + "attributes": ["speed"], + "format": "keyValues", + "endpoint": { + "uri": "http://my.endpoint.org/notify", + "accept": "application/json" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +The subject of the Context Subscription is Entities of Type Vehicle which speed +is greater than 50, and located close to a certain area defined by a reference +spatial point. Every time the speed (watched Attribute) of a concerned vehicle, +changes, a new notification (including the new speed value) will be received in +the specified endpoint. + +## C.5 Date representation + +In NGSI-LD, a _TemporalProperty_ is represented only by its value, i.e. no +sub-Properties of _TemporalProperty_ nor sub-Relationships of _TemporalProperty_ +can be conveyed. In more formal language, a _TemporalProperty_ does not allow +reification. The term _TemporalProperty_ has been reserved for non-reified +structural timestamps (_`observedAt`_}, _`createdAt`_, _`modifiedAt`_, +_`deletedAt`_), which capture the temporal evolution of Attributes. Only such +structural timestamps can be used as _`timeproperty`_ in Temporal Queries as +mandated by clause 7.2.6. + +The following examples show how time values (_Date_, _Time_, or _DateTime_) can +be represented in NGSI-LD as reified Properties. For a reified Property whose +value is assigned the JSON type _Date_, _DateTime_ or _Time_, one mechanism is +to use the Property's _`valueType`_ to hold the datatype (["Date"]{.HTML-Code}, +["Datetime"]{.HTML-Code} or ["Time"]{.HTML-Code}), as shown below: + +```json +{ + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "testedAt": { + "type": "Property", + "value": "2018-12-04T12:00:00Z", + "valueType": "DateTime" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +Alternatively the data can be a structured to use the JSON-LD _`@value`_ syntax +structure, as shown below: + +```json +{ + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "testedAt": { + "type": "Property", + "value": { + "@type": "DateTime", + "@value": "2018-12-04T12:00:00Z" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +A third alternative to achieve the same result would be to use JSON-LD "type +coercion". With type coercion, values with a special data type are defined with +_`@type`_ in the _`@context`_. This enforces the correct type for any +occurrence. Such an _`@context`_ fragment is shown below: + +```json +"testedAt": { + "@type": "https://uri.etsi.org/ngsi-ld/DateTime", + "@id": "http://example.org/test/testedAt" +} +``` + +The above does not work, when using the _`@context`_ to perform compaction, in +the normalized and compact representation of NGSI-LD, due to reification of the +Property, because in this case _`testedAt`_ is a complex JSON object, which +cannot be compacted to a _DateTime_ type as the _`@context`_ specifies. Thus, +the full URI _`http://example.org/test/testedAt`_ is kept, instead of the short +name _`testedAt`_. In summary, user _`\@contexts`_ used for the normalized and +compact NGSI-LD representation cannot use the JSON-LD type coercion feature. + +However, in the simplified (keyValue) representation case, such an _`@context`_ +with the specification of _`testedAt`_ could be used, as there is no +reification. + +As a side note, when using the above _`@value`_ + _`@type`_ approach, since +_`type`_ is mapped to _`@type`_ in the NGSI-LD core _`@context`_, JSON-LD +compaction will result in the following compacted value, instead of the one +shown above, because _`@type`_ is compacted to _`type`_: + +```json +"value": { + "type": "DateTime", + "@value": "2018-12-04T12:00:00Z" +} +``` + +## C.6 \@context utilization clarifications + +When expanding or compacting JSON-LD terms, the JSON-LD _`@context`_ to be used +is always the one provided in the current API request. For the benefit of users +and implementers the following examples illustrate this concept. + +The scenario starts with the creation of an Entity using a JSON-LD _`@context`_ +as follows: + +- **POST** +- Content-Type: application/ld+json +- Content-Length: 200 + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z" + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +The content of the _`@context`_ utilized for the referred Entity creation (at +_`http://example.org/ngsi-ld/latest/parking.jsonld`_) is as follows: + +```json +{ + "OffStreetParking": "http://example.org/parking/OffStreetParking", + "availableSpotNumber": "http://example.org/parking/availableSpotNumber", + "totalSpotNumber": "http://example.org/parking/totalSpotNumber", + "name": "http://example.org/parking/name" +} +``` + +At Entity creation time the implementation will perform the expansion of terms +using the JSON-LD _`@context`_ depicted above. + +Now it is needed to retrieve our initial Entity. For retrieving such Entity, +this time, a different JSON-LD _`@context`_ is going to be utilized, as follows: + +```json +{ + "OffP": "http://example.org/parking/OffStreetParking", + "ava": "http://example.org/parking/availableSpotNumber", + "total": "http://example.org/parking/totalSpotNumber" +} +``` + +This new _`@context`_, even though it makes use of the same set of Fully +Qualified Names, is defining new short strings as terms. The reasons for that +could be multiple: to facilitate data consumption by clients, to save some +bandwidth, to enable a more (or less) human-readable response payload body in a +language different than English, etc. + +In this particular case, the result of the Entity retrieval will be as depicted +below. It can be observed that the terms defined by the JSON-LD _`@context`_ +**provided at retrieval time** are used to render the Entity content +(compaction), and **not** the terms that were provided at creation time (which +may be no longer known by the broker). + +It is also interesting to note that the _`@context`_ array of the response +payload body contains, indeed, our header-supplied _`@context`_: + +- **GET** +- Accept: application/ld+json +- Link: + <​http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffP", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "ava": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z" + }, + "total": { + "type": "Property", + "value": 200 + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +Another interesting case to note is the one when an _`@context`_ with no +matching terms or no _`@context`_ at all is supplied. See the following example: + +- **GET** +- Accept: application/ld+json + +```json +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "http://example.org/parking/OffStreetParking", + "http://example.org/parking/name": { + "type": "Property", + "value": "Downtown One" + }, + "http://example.org/parking/availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z" + }, + "http://example.org/parking/totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" +} +``` + +In this particular case it can be observed that the user names (Entity Type, +Attributes) in the response payload body have not been compacted, and as a +result the Fully Qualified Names are included. However, the core API terms have +been compacted, as the Core _`@context`_ is always considered to be implicitly +present if not specified explicitly (and that is why it is included in the +JSON-LD response, as mandated by the specification). + +## C.7 Link header utilization clarifications + +The JSON-LD Specification [n.8] states clearly that **only one HTTP Link +header** with the link relationship +<​http://www.w3.org/ns/json-ld#context> is required to appear. Such +statement has implications in terms of providing the JSON-LD _`@context`_ when +using the NGSI-LD API. The main implication is that if the _`@context`_ is a +compound one, i.e. an _`@context`_ which references multiple individual +_`@context`_, served by resources behind different URIs, then a **wrapper** +_`@context`_ has to be created and hosted. The final aim is that only one +_`@context`_ is referenced from the JSON-LD Link header. This can be illustrated +with an example: + +Imagine that it is desired to create an Entity providing _`@context`_ terms +which are defined in two different JSON-LD _`@context`_ resources: + +- http://example.org/vehicle/v1/vehicle-context.jsonld +- https://schema.org + +If a developer wants to reference these two _`@context`_ resources from a Link +header, a wrapper _`@context`_ can be easily created as follows: + +```json +{ + "@context": [ + "http://example.org/vehicle/v1/vehicle-context.jsonld", + "https://schema.org", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +As such wrapper \@context needs to be referenced from a Link header by using a +URI, then it will have to be hosted at some place on the Web. Usually, +developers will host _`@context`_ using popular and simple solutions such as +GitHub or GitLab pages. As a result, developers will be able to use _`@context`_ +in queries or when using ["application/json"]{.HTML-Code} as main content type +managed by their applications. + +It is a **good practice to include the Core** _`@context`_ in the wrapper +_`@context`_ so it can be used, off-the-shelf, by external JSON-LD processing +tools. However, it should be noted this is not necessary for NGSI-LD, as the +Core _`@context`_ is always implicitly included. + +Then, using such wrapper _`@context`_, (in our example hosted at +https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld), the developer +will be able to issue requests like: + +- **POST** +- Content-Type: application/json +- Content-Length: 200 +- Link: + <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +```json +{ + "id": "urn:ngsi-ld:Vehicle:V1", + "type": "Vehicle", + "builtYear": { + "type": "Property", + "value": "2014" + }, + "speed": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z" + } +} +``` + +- 201 Created +- Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 +- Link: + <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld<; + rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + +​ + +- **GET** +- Accept: application/ld+json +- Link: + <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- 200 OK +- Content-Type: application/ld+json + +```json +{ + "id": "urn:ngsi-ld:Vehicle:V1", + "type": "Vehicle", + "builtYear": { + "type": "Property", + "value": "2014" + }, + "speed": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z" + }, + "@context": "https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld" +} +``` + +Observe that in this case the broker is responding with the same wrapper +_`@context`_ in the Link header of the HTTP Response or within the JSON-LD +response payload body (when MIME type accepted is +["application/ld+json"]{.HTML-Code}). However, that could not be always the +case, as there could be situations where the broker could need to provide a +wrapper _`@context`_ hosted by itself, for instance, when there are inline +_`@context`_ terms or when the Core _`@context`_ has not been previously +included by the wrapper _`@context`_ (not recommended) provided within +developer's requests. + +## C.8 \@context processing clarifications + +JSON-LD Specification [n.8] says that "If a term is redefined within a context, +all previous rules associated with the previous definition are removed". In +addition, it is stated that "Multiple contexts may be combined using an array, +which is processed in order". + +In contrast to the JSON-LD Specification, the NGSI-LD specification states that +the Core _`@context`_ is protected and has to remain immutable. This essentially +means that the Core _`@context`_ has final precedence and, therefore, is always +to be processed as the last one in the _`@context`_ array. For clarity, data +providers should place the Core _`@context`_ in the final position. From the +point of view of Data providers, care has to be taken so that there are no +unexpected or undesired term expansions. See the following example: + +```json +{ + "id": "urn:ngsi-ld:Building:B1", + "type": "Building", + "name": { + "type": "Property", + "value": "Empire State" + }, + "location": { + "type": "Property", + "value": "20 West 34th Street, New York City, NY 10001" + }, + "@context": [ + "https://schema.org/version/latest/schemaorg-current-https.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +The problem of the example above is that the term ["location"]{.HTML-Code} is +defined in both the Core _`@context`_ and the schema.org user _`@context`_ and +the Core _`@context`_ takes precedence for the expansion. In these situations, +if one wanted to refer to the schema.org ["location"]{.HTML-Code}, the solution +is to prefix the conflicting terms, so that there cannot be any clashing. +Therefore, if the intent is to refer to +<​https://schema.org/location> throughout, the example above can be +modified as shown below: + +```json +{ + "id": "urn:ngsi-ld:Building:B1", + "type": "Building", + "name": { + "type": "Property", + "value": "Empire State" + }, + "schema:location": { + "type": "Property", + "value": "20 West 34th Street, New York City, NY 10001" + }, + "@context": [ + "https://schema.org/version/latest/schemaorg-current-https.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +Note that the Core _`@context`_ should be placed in the last position of the +_`@context`_ array. NGSI-LD implementations are required to render content +following this approach, which has been undertaken in order to maximize +compatibility with JSON-LD processing tools. This example works because the +["schema:"]{.HTML-Code} prefix has already been defined by the schema.org +_`@context`_. + +## C.9 ValueType datatype utilization clarifications + +Using JSON-LD [n.8] syntax, typed values can be expressed using the JSON-LD +_`@type`_ keyword when defining a term, where _`@type`_ value holds a URI which +indicates the value's datatype. However, it can be desirable for a [Context +Broker]{.HTML-Keyboard} to be able to hold simpler untyped values within a +Property's _`value`_ attribute and separately use a Property's _`valueType`_ to +hold the value's datatype. This format can be used to accommodate multiple +acceptable datatype formats for the data to be held within a single Property and +still hold sufficient meta data to be able to distinguish between them. + +For example, consider an ontology for an Entity of type ["Place"]{.HTML-Code} +which has an _`address`_ Property, where the address Property can **either** be +an unstructured address in the form of a ["String"]{.HTML-Code} **or** a +structured ["PostalAddress"]{.HTML-Code} JSON Object with _`street`_, _`city`_ +and _`country`_ attributes - the following JSON-LD schema can be defined: + +**Example JSON-LD schema** + +```json +{ + "example": "http://example.org/", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "address": "example:address", + "city": "example:city", + "country": "example:country", + "street": "example:street", + "Place": "example:Place", + "PostalAddress": "example:PostalAddress", + "String": "xsd:String" +} +``` + +Then the following two Entities of type ["Place"]{.HTML-Code} can be created +using the _`address.valueType`_ Property to distinguish between the two formats: + +```json +[ + { + "id": "urn:ngsi-ld:Place:27182", + "type": "Place", + "address": { + "type": "Property", + "value": "Pariser Platz, Berlin, Germany", + "valueType": "String" + } + }, + { + "id": "urn:ngsi-ld:Place:31415", + "type": "Place", + "address": { + "type": "Property", + "value": { + "street": "Straße des 17. Juni", + "city": "Berlin", + "country": "Germany" + }, + "valueType": "PostalAddress" + } + } +] +``` + +## C.10 Entity with digital signature for a Property + +As specified in [n.9], the atomic piece of information that creators can +digitally sign in an NGSI-LD ecosystem is each single Attribute of an Entity. In +the following example, an Entity of type "Store" with two Properties, "address" +and "location" is presented. The "address" Property is digitally signed. The +signature is created using one Ed25519 instantiation of the Edwards-Curve +Digital Signature Algorithm (EdDSA).The used crypto suite is "eddsa-rdfc-2022". + + + + +>>> [!tip] EXAMPLE: + +Entity of type "Store" with two Properties. The "address" Property is digitally signed. + +``` json +{ + "id": "urn:ngsi-ld:Store:002", + "type": "Store", + "address": { + "type": "Property", + "value": { + "streetAddress": ["Tiger Street 4", "al"], + "addressRegion": "Metropolis", + "addressLocality": "Cat City", + "postalCode": "42420" + }, + "ngsildproof": { + "type": "Property", + "entityIdSealed": "urn:ngsi-ld:Store:002", + "entityTypeSealed": "Store", + "value": { + "type": "DataIntegrityProof", + "created": "2025-01-27T21:02:24Z", + "verificationMethod": "https://example.edu/issuers/565049#z6MkwXG2WjeQnN....Hc6SaVWoT", + "cryptosuite": "eddsa-rdfc-2022", + "proofPurpose": "assertionMethod", + "proofValue": "z3XrH3diVCqpVHXkE7WbnictqyQCkJBGTx....NRTzmuoWU1Y2FyqGfSV9eS" + } + } + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [57.5522, -20.3484] + } + }, + "@context": "https://uri.etsi.org/ngsi-ld/primer/store-context.jsonld" +} +``` + +>>> + + diff --git a/md/annex-change_history.md b/md/annex-change_history.md new file mode 100644 index 0000000000000000000000000000000000000000..a221a29c596d5b5c81d6f3072c016be264763cb4 --- /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/annex-d.md b/md/annex-d.md new file mode 100644 index 0000000000000000000000000000000000000000..11cd30f76f8a3842b0f38773dbee58a269d881bf --- /dev/null +++ b/md/annex-d.md @@ -0,0 +1,162 @@ +# Annex D [(informative)]{.inform}: Transformation algorithms + +## D.1 Introduction + +These algorithms are informative but NGSI-LD implementations should aim at +either implementing them as they are described here or devising similar +algorithms which take exactly the same input and provides exactly the same +output (or an equivalent one as per the JSON-LD specification [n.8]). + +## D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1) + +This algorithm takes as input an NGSI-LD graph which top level node is a +particular Entity and returns as output a JSON-LD document which represents all +the data associated to the entity. The JSON-LD document (and its associated +_`@context`_) corresponds to a representation of the Entity in JSON-LD as per +the NGSI-LD Information Model. + + + +>>> [!note] NOTE: + +An early implementation of this algorithm can be found at [i.21]. + +>>> + + + +Let: + +- **G** be a graph defined as follows: + - Let **N** be G's top level node. + - N is an Entity instance of type **T** or types **Ts**. Type name is "AliasT" + or there is an Array of Type names ["AliasT1", ...,"AliasTn"], N's + identifier is **I**. + - N has 0 or more associated _Property_. Each _Property_ (**Psi**) is defined + as follows: + - _Property_ type identifier is **Pi**. + - _Property_ name is "AliasPi". + - _Property_ Value is **Vi**. + - _Property_ Value's associated data type is **Di**. + - N is the subject of 0 or more _Relationship_. Each _Relationship_ is defined + as follows: + - _Relationship_ type identifier is **Ri**. + - _Relationship_ name is "AliasRi". + - _Relationship_ target object identifier is **Robji**. +- **O** be a JSON object initialized to the empty object ({}). +- **C** be a JSON-LD _`@context`_ initialized as described by annex B. + +The algorithm should run as follows, provided all the preconditions defined +above are satisfied: + +1. Add to C a new member <"AliasT", T> or new members <"AliasT1", T1> ... + <"AliasTn", Tn>. + +2. Add to O two new members: + + + + a. <"id", I>. + b. <"type", "AliasT"> or <"type", "AliasT1", ...,"AliasTn"> .">. + + + +3. For each _Property_ Psi (Pi, "AliasP", Vi, Di) associated to N: + + + + a. Run Algorithm ALG1.1 taking the following inputs: + - Ps → Psi. + - O → O. + - C → C. + + + +4. For each _Relationship_ Rs (Ri, AliasRi, Robji) associated to N: + + + + a. Run Algorithm ALG1.2 taking the following inputs: + - Rs → Rsi. + - O → O. + - C → C. + + + +5. Return (O, C) and end of the algorithm. + +## D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1) + +Let **Ps** be the _Property_ that has to be transformed. It is defined by (P, +"AliasP", V, D), where **P** denotes a _Property_ Type Id, "**AliasP**" is the +_Property_ name, **V** is the _Property_ Value and **D** is the _Property_ +Value's data type. + +Ps might be associated to extra _Properties_ or _Relationships_. + +Let O be the output JSON-LD object and C the associated JSON-LD context: + +1. Execute the following steps: + + + + a. If no member with "AliasP" is present in O, add a new member to O with + key "AliasP" and value an object structure, let it be named **Op** + <"type", "Property">. + - If D is not a native JSON data type add a new member to Op with name + "value" and which value has to be an object structure as follows: + 1. <"@type", D>. + 2. <"@value", V>. + - Else If D is a native JSON data type add a new member to Op as follows: + 1. <"value", V>. + b. Add a new member to C as follows: + - <"AliasP", P>. + c. For each _Property_ associated to Ps (Pss) + recursively run the present algorithm (ALG1.1) taking the following + inputs: + - Ps → Pss. + - O → Op. + - C → C. + d. For each _Relationship_ associated to Ps (Rss) run + algorithm ALG1.2 taking the following inputs: + - Rs → Rss. + - O → Op. + - C → C. + + + +2. Return (O,C) and end of the algorithm. + +## D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2) + +Let **Rs** be the _Relationship_ that has to be transformed. It is defined by +(R, "AliasR", Robj), where **R** denotes a _Relationship_ Type Id, "**AliasR**" +is the _Relationship_'s name and **Robj** is the identifier of the target object +of the _Relationship_. + +Rs might be associated to extra _Properties_ or _Relationships_. + +Let O be the output JSON-LD object and C the current JSON-LD context: + +1. Execute the following statements: + + + + a. If no member with "AliasR" is present in O, add a new member to O with + key "AliasR" and value an object structure, let it be named **Or** + - <"object", Robj>. + - <"type", "Relationship">. + b. For each _Property_ associated to Rs (Pss) run the + algorithm ALG1.1 taking the following inputs: + - Ps → Pss. + - O → Or. + - C → C. + c. For each _Relationship_ associated to Rs (Rss) + recursively run the present algorithm ALG1.2 taking the following inputs: + - Rs → Rss. + - O → Or. + - C → C. + + + +2. Return (O,C) and end of the algorithm. diff --git a/md/annex-e.md b/md/annex-e.md new file mode 100644 index 0000000000000000000000000000000000000000..a6b25d2890960cc4d221e7c8b1d3c70fc4dd7623 --- /dev/null +++ b/md/annex-e.md @@ -0,0 +1,3 @@ +# Annex E [(informative)]{.inform}: RDF-compatible specification of NGSI-LD meta-model + +The content of this annex is now in ETSI TS 104 178 [i.6]. diff --git a/md/annex-f.md b/md/annex-f.md new file mode 100644 index 0000000000000000000000000000000000000000..7d44c8b7778dee1d02d0d32087fdeb94f283ef7d --- /dev/null +++ b/md/annex-f.md @@ -0,0 +1,107 @@ +# Annex F [(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-g.md b/md/annex-g.md new file mode 100644 index 0000000000000000000000000000000000000000..8c1d7bc814232dce589d700a14a550e218981410 --- /dev/null +++ b/md/annex-g.md @@ -0,0 +1,232 @@ +# Annex G [(informative)]{.inform}: Localization and internationalization support + +## G.1 Introduction + +These algorithms described below are informative, but NGSI-LD implementations +should aim at either implementing them as they are described here or providing +equivalent _`@context`_ elements for their payloads to provide interoperability +with their internationalized context entities. + +## G.2 Localization and internationalization + +### G.2.1 Introduction + +Since Internationalization is not core to context information management, any +direct support within NGSI-LD systems is limited. Annex+++root proposes a series +of best practices for maintaining, querying and displaying interoperable +internationalized data. + +The content of the _`@context`_ utilized for the referred Entities within these +examples uses pre-existing URNs used for internationalization and is as follows: + +```json +{ + "inLanguage": "http://schema.org/inLanguage", + "sameAs": "http://schema.org/sameAs" +} +``` + +### G.2.2 Associating an Entity with a natural language + +Where a context Entity is associated with a single natural language, include a +well-defined _Property_ indicating the natural language of the content. For +example an Event taking place in French may be defined as follows: + +```json +{ + "type": "Event", + "id": "urn:ngsi-ld:Event:bonjourLeMonde", + "name": { + "type": "Property", + "value": "Bonjour le Monde" + }, + "description": { + "type": "Property", + "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple" + }, + "inLanguage": { + "type": "Property", + "value": "fr" + } +} +``` + +### G.2.3 Associating a Property with a natural language + +Where a _Property_ of a context entity can be associated to one more natural +language, include additional metadata as a sub-Property of that _Property_. For +example, a Hotel with booking forms available in English, French and German may +be defined as follows: + +```json +{ + "type": "Hotel", + "id": "urn:ngsi-ld:Hotel:XXXXX", + "name": { + "type": "Property", + "value": "Grand Hotel" + }, + "bookingUrl": { + "type": "Property", + "value": [ + "http://example.com/booking-in-french/", + "http://example.com/booking-in-english/", + "http://example.com/booking-in-german/" + ], + "inLanguage": { + "type": "Property", + "value": ["fr", "en", "de"] + } + } +} +``` + +### G.2.4 Associating as equivalent Entity + +Where equivalent context entities in multiple natural languages exist, they may +be associated with each other through the use of a one-to-many _Relationships_, +where each _Relationships_ holds an additional sub-Property indicating the +natural language of the equivalent entities. + +For example, three Events (such as a walking tour which is available in English, +French and German) may be associated to each other as follows: + +```json +{ + "type": "Event", + "id": "urn:ngsi-ld:Event:bonjourLeMonde", + "name": { + "type": "Property", + "value": "Bonjour le Monde" + }, + "sameAs": [ + { + "type": "Relationship", + "datasetId": "urn:ngsi-ld:Relationship:1", + "object": "urn:ngsi-ld:Event:helloWorld", + "inLanguage": { + "type": "Property", + "value": "en" + } + }, + { + "type": "Relationship", + "object": "urn:ngsi-ld:Event:halloWelt", + "inLanguage": { + "type": "Property", + "value": "de" + } + } + ] +} +``` + +## G.3 Natural language collation support + +### G.3.1 Introduction + +All strings within an NGSI-LD system are defined and sorted as a sequence of +Unicode characters. As such there is no simple collation mechanism to query +entities ignoring case, diacritic marks or matching diphthong single letters +such as the German ["ö"]{.HTML-Code} to also match with ["oe"]{.HTML-Code}. + +Many databases support a degree of natural language support, in general +collation support will always depend upon the underlying database and as such +will vary from implementation to implementation. This therefore and cannot be +standardized and exposed as part of the context information management API. +Furthermore, collation is slow and processor intensive, and for massive systems +is better achieved using a separate index. + +For systems that require it, this clause proposes a mechanism as an extension to +a NGSI-LD [Context Broker]{.HTML-Keyboard} which can be modified and used to +offer collation support to the natural language attributes found within context +entities where necessary through creating, querying and maintaining an +additional property of a property for collated attributes. + +### G.3.2 Maintain collations as metadata + +- Create a subscription on the attribute (e.g. _`name`_) +- Create a simple microservice to add/upsert a _`name.collate`_ + property-of-a-property using a simple function to strip all diacritic marks - + for example: [str.normalize("NFD").replace(/\[\\u0300-\\u036f\]/g, + "").toLower()]{.HTML-Sample} + +Other substitutions could be made where local spelling rules vary (for example +different for German ö = oe). + +### G.3.3 Route language sensitive queries via a proxy + +Create a simple forwarding proxy around the NGSI-LD system. For any urls with a +_`q`_ param (and a _`collate`_ flag) run a clean-up of the _`q`_ param and amend +the query string: + +The following request on the proxy: + +- **GET** + _`/ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name`_ + +is altered on the fly and is sent to the NGSI-LD system as shown: + +- **GET** + _`/ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22`_ + +Once again, the substitutions to make to the query string will depend on the +rules of the natural language to be supported. + +## G.4 Localization of dates, currency formats, etc. + +### G.4.1 Introduction + +Context data entities are designed to be interoperable and therefore all dates +are held as UTC dates, all currency amounts are held as JSON numbers (with the +unitCode property-of-a-property available to hold the currency), etc. +Localization should not occur within the context data entities themselves. +Offering fully localized responses is not a concern of the NGSI-LD API. + +If localization support is necessary, a simple proxying a conversion mechanism +could be used to amend the context data received from the NGSI-LD system before +being passed to a third party system for display. + +### G.4.2 Localizing dates + +For example, if a system needs to display _DateTime_ data in Islamic Date format + +The following request on the proxy: + +- **GET** + _`/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified`_ + +is forwarded unaltered and is sent to the NGSI-LD system as shown: + +- **GET** + _`/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified`_ + +The response from the NGSI-LD system is always in UTC format: + +```json +{ + "date": "2020-09-28T17:13:39+02:00" +} +``` + +And the proxy can be used to update this to the desired format: + +```json +{ + "date": "11 Safar, 1442 1:13:39PM" +} +``` + +Using an internationalization script such as the following: + +```js +new Intl.DateTimeFormat("en-u-ca-islamic", { + day: "numeric", + month: "long", + weekday: "long", + year: "numeric", +}).format(date); +``` + +It should be noted that post-localization, the transformed date is no longer +valid NGSI-LD. diff --git a/md/annex-h.md b/md/annex-h.md new file mode 100644 index 0000000000000000000000000000000000000000..be491185ce9cfbe24991280639dea7a9b3ecf69f --- /dev/null +++ b/md/annex-h.md @@ -0,0 +1,579 @@ +# Annex H [(informative)]{.inform}: Suggested actuation workflows + +## H.1 Actuators and feedback to the consumer + +Actuators are things that can change their state (light on/off) or execute +actions (move forward, detect face, etc.). + +There is currently no explicitly and precisely specified support for actuation +in the NGSI-LD API. Thus, this clause describes some conventions that represent +a proposed best-practice about how NGSI-LD API and data models can be used for +the interaction between applications and actuators represented by NGSI-LD +Entities. + +The conventions and approach described in this clause are not powerful enough to +implement complex actuation jobs that depend on each other and, for instance, +make actuation decisions conditional on the outcome of other actuations, unless +that behaviour is implemented in a custom way within the application logic. The +concept of a more evolved service execution logic, being a first-class citizen +of the NGSI-LD API and able to offer more structured building blocks for +actuation, is outside the scope of this annex. + +An NGSI-LD system that comprises an actuator and supports actuation workflows is +represented as one or more NGSI-LD Entities, plus a [Context +Broker]{.HTML-Keyboard}, a [Context Source]{.HTML-Keyboard} or a [Context +Producer]{.HTML-Keyboard}, and a [Context Consumer]{.HTML-Keyboard}, which +collaborate. + +The interaction between actuator and [Context Consumer]{.HTML-Keyboard} needs to +be bidirectional. Thus, actuators are triggered by the reception of +actuation-specific commands (e.g. "set the on state of the lamp to false", to +turn the light off) that are encoded as NGSI-LD data, following a suggested data +model. They respond with feedback, similarly encoded as NGSI-LD data. + +Command feedbacks may serve to control the maximum operations rate a controlling +application needs to achieve, and different levels of feedback can be requested, +by associating a specific Quality of Service value to the command: + +- Some applications need high operation rate but no feedback. For this case a + QoS = 0 can be used. The typical example is to control the arms of a robot + with a joystick. +- Some applications need to be sure that the actuators actually received the + command request or need to get back a payload in response to the command. In + this case a QoS = 1 can be used. The typical case is switching on a light with + confirmation, or request face-detection with consequent notification of + matching events. +- Commands can either require a short or a long execution time. For commands + with long execution time, the application may require a continuous status + feedback. In this case a QoS = 2 can be used. The typical example is that of a + door opening, where feedback continuously reports the current level (10 % + open, 50 % open, etc.). + +## H.2 Architecture for actuation + +In this architecture, the application acts as [Context +Consumer]{.HTML-Keyboard}, and the terms are used interchangeably. + +Commands are sent to the [Context Broker]{.HTML-Keyboard} by the [Context +Consumer]{.HTML-Keyboard}, using the standard NGSI-LD API and a suggested +convention for representing them. In turn, feedback about command execution is +received by the [Context Consumer]{.HTML-Keyboard}, both as continuous status +updates and/or a final command result. + +More specifically, the component that handles direct communication with the +actuator is the [Context Source]{.HTML-Keyboard} or the [Context +Producer]{.HTML-Keyboard}: it uses an actuator-specific protocol to control the +actuator and get responses and updates from it, i.e. from the real system. Such +[Context Source]{.HTML-Keyboard}/Consumer or [Context +Producer]{.HTML-Keyboard}/Storage acting as a proxy or intermediary to the +actuator is referred to, in the following, as Context Adapter. + +Thus, the Context Adapter is able to use the NGSI-LD API to receive NGSI-LD +command requests from the NGSI-LD [Context Broker]{.HTML-Keyboard} and send back +command status and result to it, as well as using an actuator-specific protocol +to communicate with the actuator. + +The NGSI-LD [Context Broker]{.HTML-Keyboard} is responsible for handling direct +communication with the [Context Consumer]{.HTML-Keyboard}. + +Thus, to support actuation, there is a need to specify: + +- Additional NGSI-LD Properties the NGSI-LD system has to have, in order to + represent and manage command Request, Status, Result. +- A communication model that allows commands to flow in forward direction and + feedback to flow in reverse. This communication model has to comprise a + mapping, to be held within the NGSI-LD system, that is able to route the + command requests to the appropriate handler within the Context Adapter and + vice-versa. + + + +::: FL + +::: + +::: TF +Figure: Architecture for actuation +::: + + + +## H.3 Structure of commands and additional Properties + +### H.3.1 Introduction + +The NGSI-LD system has, in addition to the usual NGSI-LD Properties representing +the actuator's status, a set of additional, dedicated NGSI-LD Properties +associated with: + +- the list of available commands, i.e. the list of commands supported by the + actuator; +- command endpoints, one for each command, that are used to send and receive + command related messages and optionally hold state for the ongoing commands. + +The structure of the commands needs to be specified, but not the internal format +of their payloads. By using commands with a custom payload, one can support all +kinds of operations, for example: + +- ["set-on": "true"]{.HTML-Sample} +- ["detect-face": {"face-features": "...."}]{.HTML-Sample} +- ["move": "forward"]{.HTML-Sample} + +The data model for command requests, status and responses has to include +metadata such as the QoS of the command, its identifier, and the custom payload +itself. + +Both the requests/responses and the list of commands the NGSI-LD system is able +to support can be represented with additional NGSI-LD Properties, as follows. + +### H.3.2 Property for listing available commands + +The additional _Property_ dedicated to the list of available commands is as +follows: + +```json +"commands": { + "type": "Property", + "value": ["<​cmd_name1>", "<​cmd_name2>", …, "<​cmd_nameN>"] +} +``` + +It is a _Property_ whose value is an array of Strings, each string representing +the unique name of a supported command. + +### H.3.3 Properties for command endpoints + +For each available command, a set of three endpoints is to be additionally +created within the NGSI-LD system, by means of three dedicated _Properties_ per +command. The first endpoint will manage that command's requests, the second +endpoint will manage its status, and the third endpoint will manage command's +results. + +This convention dictates that: + +- The NGSI-LD _Property_ that manages requests has the same name as the command, + e.g. ["<​cmd_name1>"]{.HTML-Code}. +- The NGSI-LD _Property_ that manages results has the same name as the command + plus the ["-RESULT"]{.HTML-Code} suffix. +- The NGSI-LD _Property_ that manages status has the same name as the command + plus the ["-STATUS"]{.HTML-Code} suffix. + +Each endpoint can receive multiple requests or responses, and it supports +queueing of messages. For example, the command _`moveToLocation`_ may receive a +sequence of requests that are to be stored in an array and orderly processed +depending on the arrival timestamps. A number of respective responses may be +produced, as well. Thus, each endpoint, represented by its dedicated NGSI-LD +_Property_, exploits the multi-Attribute feature (see Clause+++clause-8+++8.5), +as follows: + +**Command Request endpoint** + +```json +"<​cmd_name>": { + "datasetId": "a URI uniquely identifying the specific command request + (optional, if the use case does not need command queueing)", + "type": "Property", + "qos": "an Integer, representing the desired QoS (optional, default=0)", + "value": "custom parameters of the command (mandatory)" +} +``` + +**Command Status endpoint** + +```json +"<​cmd_name>-STATUS": { + "datasetId": "a URI uniquely identifying the specific status feedback message + (optional, if the use case does not need queueing them)", + "type": "Property", + "value": "custom status of the command (mandatory)" +} +``` + +**Command Result endpoint** + +```json +"<​cmd_name>-RESULT": { + "datasetId": "a URI uniquely identifying the specific result feedback message + (optional, if the use case does not need queueing them)", + "type": "Property", + "value": "custom result of the command (mandatory)" +} +``` + +Usually, the Context Adapter (or the actuator behind it), upon receiving a +command request with a specific _`datasetId`_, will then generate status and +result with the same _`datasetId`_, so that, when the status/result is received +by the application, it can link it back to the corresponding command that is +generating the received feedback. The value of the request, status and result is +generic, and it is up to the specific application to define useful values. As an +example, the PackML language for the control of packaging machines defines a set +of possible values for statuses during an actuation workflow. + + + +>>> [!tip] EXAMPLE 1: + +An example follows, where the NGSI-LD system represents a simple actuator. The +example shows the NGSI-LD Entity representing a light that can change colour by +manipulation of its brightness, hue and saturation values; further, it is +possible to turn the lamp on and off. Apart from the _`id`_ and +the _`type`_, the actuator entity has a set of regular properties +that represent the current status of the lamp. In the example these are +_`colorRGB`_ and _`is-on`_. Then it has the +conventional _Property_ named _`commands`_, +signalling that it supports four commands: ["turn-on"]{.HTML-Code}, +["set-saturation"]{.HTML-Code}, ["set-brightness"]{.HTML-Code}, +["set-hue"]{.HTML-Code}. Further, it has four (times three) additional +properties serving the purpose of command endpoints. + +```json +{ + "id": "urn:ngsi-ld:pHueActuator:light1", + "type": "Lamp", + // REGULAR PROPERTIES + "colorRGB": {"type": "Property", "value": "0xABABAB"}, + "is-on": {"type": "Property", "value": true}, + // AVAILABLE COMMANDS + "commands": { + "type": "Property", + "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"] + }, + // COMMAND ENDPOINTS + "turn-on": {"type": "Property", "value": "<​custom request>"}, + "turn-on-STATUS": {"type": "Property", "value": "<​custom status>"}, + "turn-on-RESULT": {"type": "Property", "value": "<​custom response>"}, + "set-hue": … , + "set-hue-STATUS": … , + "set-hue-RESULT": … , + … +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +The following example shows an NGSI-LD Entity Fragment that can be used as a +command request to request that the lamp be turned off. + +```json +{ + "id": "urn:ngsi-ld:pHueActuator:light1", + "type": "Lamp", + "turn-on": { + "type": "Property", + "qos": { + "type": "Property", + "value": 1 + }, + "value": false + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +In the following example, the value of the command request is a more complex +JSON Object, to show that complex actions can be conveyed by just one request. +Further, the request has an identifier that makes it possible to enqueue it, +together with other request that may arrive to the same command endpoint within +a timespan. + +```json +{ + "id": "urn:ngsi-ld:pHueActuator:light1", + "type": "Lamp", + "set-hue": { + "type": "Property", + "qos": { + "type": "Property", + "value": 1 + }, + "datasetId": "myapp:mycommand:1342", + "value": { "red": "1 seconds", "green": "2 seconds" } + } +} +``` + +>>> + + + +In summary, the suggested convention prescribes a _`commands`_ _Property_ that +contains a list of commands supported by the actuator. For each of these +commands, the convention requires a command endpoint consisting of three +properties, the name of the command, e.g. ["turn-on"]{.HTML-Code}, the status +_Property_, which is the name of the command with ["-STATUS"]{.HTML-Code} as +suffix, and the result, which is the name of the command with +["-RESULT"]{.HTML-Code} as suffix. Nevertheless, it is noted that such suffixes +are just a convention to distinguish the endpoints. So far, two practical +implementations exist, see Clause+++root.5 and Clause+++root.6, that adopt the +general scheme of this convention, with minor deviations. In fact, this +convention is derived as a generalization that leverages the full potential of +NGSI-LD sub-Attributes and multi-Attributes. + +## H.4 Communication model + +### H.4.1 Possible communication models + +This convention can be leveraged by two different communication models: + +- Subscription/notification, where both the application and the Context Adapter + use NGSI-LD Subscriptions to have the command requests delivered to the + appropriate handler within the Context Adapter and vice-versa. In this case + the Context Adapter acts as a [Context Source]{.HTML-Keyboard} as well as a + [Context Consumer]{.HTML-Keyboard}. +- Forwarding, which uses the NGSI-LD Registry and a Context Adapter able to + federate itself with the [Context Broker]{.HTML-Keyboard} holding the + actuator's Entity, as a means to deliver the commands. In this case the + Context Adapter acts as a Context Storage as well as a [Context + Producer]{.HTML-Keyboard}. + +### H.4.2 Subscription/notification model + +For the interaction to work, the Context Adapter, acting as a proxy to the +actuator, subscribes to all command properties; in example 1 of +Clause+++root.3.3, these are ["set-brightness"]{.HTML-Code}, +["set-saturation"]{.HTML-Code}, ["set-hue"]{.HTML-Code} and +["turn-on"]{.HTML-Code}. When the application, acting as the actuation client, +updates the value of a command property, the Context Adapter will receive the +notification with the new value. This will be translated into the proprietary +format and forwarded to the actuator using the actuator-specific protocol. The +application in turn can subscribe to the command status and the result. The +Context Adapter updates the status of the actuation during the execution of the +command, which is primarily relevant in the case of longer-lasting actuations, +and finally updates the result once the actuation has been completed. If the +application has subscribed to the status and result, it will receive the +corresponding notifications. Independent of the command-related properties, the +status of the actuator, held within its regular properties, will be updated. + +The detailed workflow is depicted in Figure+++below, and can be interpreted as +follows: + +1. Application updates _`turn-on`_ command Property with ["value": + true]{.HTML-Code} +2. Context Adapter gets notification of the new value _`true`_ +3. Context Adapter updates _`turn-on-STATUS`_ command Property with ["value": + "PENDING"]{.HTML-Code} +4. Application gets notification of the new value ["PENDING"]{.HTML-Code} +5. Context Adapter updates _`is-on`_ regular Property with ["value": + true]{.HTML-Code} +6. Application gets notification with value: [true]{.HTML-Code} +7. Context Adapter updates _`turn-on-RESULT`_ command Property with ["value": + "OK"]{.HTML-Code} +8. Application gets notification with of the new value ["OK"]{.HTML-Code} + + + +::: FL + +::: + +::: TF +Figure: Steps of the actuation workflow using subscription/notification +::: + + + +### H.4.3 Forwarding model + +The forwarding model uses registrations and forwarding of requests. Actuation of +commands is provisioned via registration(s) to the NGSI-LD Registry done by the +Context Adapter that states "I am responsible for command property +<​X>". When the Application changes the value of a command property, +first the NGSI-LD [Context Broker]{.HTML-Keyboard} asks to the NGSI-LD Registry +whether the property is delegated to some other component. The NGSI-LD Registry +knows that property <​X> of the Entity is delegated to the Context +Adapter. Hence, the request is forwarded to the Context Adapter. Similar to the +other communication model, the request will then be translated into the +proprietary format and forwarded to the actuator using the actuator-specific +protocol. + +In this model, the NGSI-LD Entity is distributed over two different components, +because some of its properties live in the [Context Brokers]{.HTML-Keyboard} and +other properties live in the Context Adapter, as indicated in Figure+++below +with a dotted rectangle. + +The rest of the workflow, i.e. delivery of status and result messages to the +application, is done similarly to the subscription/notification model. The +detailed workflow is depicted in Figure+++below, and can be interpreted as +follows: + +1. Application updates _`turn-on`_ command _Property_ with ["value": + true]{.HTML-Code} +2. a. [Context Broker]{.HTML-Keyboard} ask Registry where to forward the + request b. [Context Broker]{.HTML-Keyboard} forwards request to Context + Adapter +3. Context Adapter updates _`turn-on-STATUS`_ command _Property_ with ["value": + "PENDING"]{.HTML-Code} +4. Application gets notification of the new value ["PENDING"]{.HTML-Code} +5. Context Adapter updates _`is-on`_ regular _Property_ with ["value": + true]{.HTML-Code} +6. Application gets notification with value:[true]{.HTML-Code} +7. Context Adapter updates _`turn-on-RESULT`_ command _Property_ with ["value": + "OK"]{.HTML-Code} +8. Application gets notification with the new value["OK"]{.HTML-Code} + + + +::: FL + +::: + +::: TF +Figure: Steps of the actuation workflow using forwarding +::: + + + +## H.5 Implementation of the subscription-based actuation workflow + +The [Fed4IoT project](https://fed4iot.org) leverages the NGSI-LD architecture +and the subscription/notification workflow for actuation, in order to implement +the concept of a Cloud of Things. It enables virtualization of existing IoT +sensors/actuators through Virtual Things and IoT Brokers. IoT application +developers can simply rent the Virtual Things and the Brokers their applications +need. + +The Fed4IoT's Cloud of Things is named +[VirIoT](https://github.com/fed4iot/VirIoT), and it is based on the concept of +Virtual Silos as-a-service: isolated and secure IoT environments made of Virtual +Things whose data can be accessed through standard IoT Brokers (oneM2M, NGSI, +NGSI-LD, etc.). + +In Figure+++below a diagram shows how VirIoT implements the concept of a +large-scale and distribute NGSI-LD system that leverages the architecture and +the workflow convention described in Clause+++root.4.2. + + + +::: FL + +::: + +::: TF +Figure: VirIoT implementation of the NGSI-LD system and actuation workflow +::: + + + +All components encapsulate requests in a neutral-format message that leverages +NGSI-LD Entities at its core. But, since VirIoT uses MQTT as its internal data +distribution system, all information and actuation commands are encoded as +NGSI-LD entities, plus an additional "meta header" that is used by the MQTT to +publish and subscribe in a broadcast fashion to multiple vThings, because the +same virtual sensor can be used by multiple applications at the same time. + +For the actuation workflow, the "data" part of this message contains the command +request, as specified in clause+++root.3, but with an additional value key that +is the "command notification uri" ([cmd-nuri]{.HTML-Sample}), representing a +location where feedback (status, result) should be sent by the ThingVisor. For +example, the [cmd-nuri]{.HTML-Sample} contains the "data_in" MQTT topic of the +issuing vSilo, so that command feedbacks (status and results) are sent to it, +only, instead of being broadcasted to all subscribing applications. + +VirIoT is agnostic to access control issues to a virtual actuator, since the +relevant policies are implemented in the specific ThingVisor, which can grant +tokens to execute actuation-commands to a subset of vSilos only, through +preliminary exchange of specific actuation-commands (a kind of log-in). + +Fed4IoT has developed several different ThingVisors (Context Adapters for +different sensors and hardware): for example, lamp systems and robot devices are +virtualized through specific ThingVisors, and applications can control the +lighting system of a rented conference room or control camera and position of a +bot by adding related virtual actuators to their vSilo. + +## H.6 Implementation of the registration-based actuation workflow + +The IoT Agent node library [i.22] introduces the concept of an IoT Agent, which +is a component that lets a group of devices send their data to and be managed +from a [Context Broker]{.HTML-Keyboard} using their own native protocols. Thus, +it corresponds to the Context Adapter, and wires up the IoT devices so that +measurements can be read and commands can be sent using NGSI-LD requests sent to +an NGSI-LD compliant context [Context Broker]{.HTML-Keyboard}. + +IoT Agents already exist or are in development for many IoT communication +protocols and data models. Examples include the following: + +- IoTAgent-JSON - a bridge between HTTP/MQTT messaging (with a JSON payload) and + NGSI-LD +- IoTAgent-LWM2M - a bridge between the Lightweight M2M protocol and NGSI-LD +- IoTAgent-UL - a bridge between HTTP/MQTT messaging (with an UltraLight2.0 + payload) and NGSI-LD +- IoTagent-LoRaWAN - a bridge between the LoRaWAN protocol and NGSI-LD + +This implementation follows the communication model described in +Clause+++root.4.3, as explained in Figure+++below. In this workflow: + +- Requests between User and [Context Broker]{.HTML-Keyboard} use NGSI-LD +- Requests between [Context Broker]{.HTML-Keyboard} and IoT Agent use NGSI-LD +- Requests between IoT Agent and IoT Device use native protocols +- Requests between IoT Device and IoT Agent use native protocols +- Requests between IoT Agent and [Context Broker]{.HTML-Keyboard} use NGSI-LD + + + +::: FL + +::: + +::: TF +Figure: IoT Agent node library implementation of the NGSI-LD system and actuation workflow +::: + + + +Provisioning of the devices will be carried out (via REST API) through IoT +Agents, as well. This provisioning implies that, on the one hand, the +corresponding entities (with their commands), that represent the devices, are +generated in the [Context Broker]{.HTML-Keyboard} and, on the other hand, that +the corresponding IoT Agent is configured for communication with the +corresponding device, all in one provisioning step. Below, an example how to +provision a device which supports start and stop commands is presented. + +```json +{ + "devices": [ + { + "device_id": "device001", + "entity_name": "urn:ngsi-ld:Device:001", + "entity_type": "Device", + "attributes": [ + { + "object_id": "s", + "name": "isOpen", + "type": "boolean" + } + ], + "commands": [ + { + "name": "start", + "type": "command" + }, + { + "name": "stop", + "type": "command" + } + ], + "static_attributes": [ + { + "name": { + "type": "Text", + "value": "Device:001 provision" + } + } + ] + } + ] +} +``` diff --git a/md/clause-10.md b/md/clause-10.md new file mode 100644 index 0000000000000000000000000000000000000000..f0c8bfc7386bcd28411707de1afb9b2c75267755 --- /dev/null +++ b/md/clause-10.md @@ -0,0 +1,2858 @@ +# 10 Core API operations + +## 10.1 Introduction + +Clause 10 defines the operations that allow [Context Producers]{.HTML-Keyboard} +to create, modify, and delete context information within an NGSI-LD system, as +well as the operations that allow [Context Consumers]{.HTML-Keyboard} to +retrieve context information from an NGSI-LD system. + +Each operation is described in terms of its purpose, input data, behaviour, and +output data. Where applicable, use case diagrams illustrate the interactions +between actors and the NGSI-LD system for each operation. + +## 10.2 Context information provision + +### 10.2.1 Introduction + +Clause 10.2 defines the operations that allow [Context +Producers]{.HTML-Keyboard} to create, modify, and delete context information +within an NGSI-LD system. + +### 10.2.2 Create Entity + +#### 10.2.2.1 Description + +This operation allows creating a new NGSI-LD Entity. + +#### 10.2.2.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can create an Entity within an NGSI-LD +system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Create entity use case +::: + + + +#### 10.2.2.3 Input data + +A JSON-LD document representing an NGSI-LD Entity as mandated by clause +5.2.6.4.1. + +#### 10.2.2.4 Behaviour + +Implementations shall exhibit the following behaviour: + +- Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. +- If an **exclusive** [Context Source Registration]{.HTML-Keyboard} already + exists for this Entity id (URI), Attributes from matching input data are + forwarded for remote processing: + - For matching Registrations where the Create Entity operation is supported, + the operation is forwarded to the registration endpoint. If the endpoint + then raises an error, this shall result in an error in case the complete + create failed or in a partial success if some parts of the create succeeded. + + - For matching Registrations where the Create Entity operation is not + supported, this shall result in an error of type [Conflict]{.HTML-Error} if + the complete Create Entity operation failed or in a partial success if some + parts of it succeeded. + + The matching Attributes are then removed from the Fragment and not processed + further. + +- If any **redirect** [Context Source Registrations]{.HTML-Keyboard} exist that + match against the input data, that input data is forwarded for remote + processing by one or more matching endpoints: + - For matching Registrations where the Create Entity operation is supported, + matching input data is forwarded. If any such endpoint then raises an error, + this shall result in an error in case the complete create has failed or in a + partial success if some parts of the create has succeeded. + - For matching **redirect** Registrations where the Create Entity operation is + not supported, this shall result in an error of type [Conflict]{.HTML-Error} + if the complete Create Entity operation failed or in a partial success if + some parts of it succeeded. + +- The matching Attributes are then removed from the Fragment and not processed + further. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded for + remote processing by matching endpoints in case the Create Entity operation is + supported. +- If the Entity already exists locally this shall result in an error of type + [AlreadyExists]{.HTML-Error}, if the complete Create Entity operation has + failed or in a partial success if some parts of it has succeeded. +- Any remaining input data shall be used to create the Entity locally. + +#### 10.2.2.5 Output data + +A URI identifying the newly created Entity. + +### 10.2.3 Update Attributes + +#### 10.2.3.1 Description + +This operation allows modifying an existing NGSI-LD Entity by updating **already +existing** Attributes (Properties or Relationships) and by appending +non-existing ones. + +#### 10.2.3.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can update Attributes within an NGSI-LD +system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Update Attributes use case +::: + + + +#### 10.2.3.3 Input data + +- A URI representing the id of the Entity to be updated (target Entity). +- A selector of Entity types as specified by clause 7.2.2 (optional). +- A JSON-LD document representing an NGSI-LD Entity Fragment. + +#### 10.2.3.4 Behaviour + +- If the Entity ID is not present or it is not a valid URI then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI), and where specified type, is equivalent + to the target entity held locally, and no matching registrations apply (see + clause 9.4), an error of type [ResourceNotFound]{.HTML-Error} shall be raised. +- Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. NGSI-LD + Nulls should be supported by this operation. If NGSI-LD Nulls are found in the + payload, but are not supported, an error of type + [OperationNotSupported]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, Attributes from + matching input data are forwarded for remote processing. For each matching + registration: + - If the Update Attributes operation is supported by the registration (see + clause 9), matching input data is forwarded to the Registration endpoint. + - If the Update Attributes operation is not supported by the registration, + this shall result in an error of type [Conflict]{.HTML-Error} if the + complete update failed or in a partial success if some parts of the update + succeeded. + +- The matching Attributes are then removed from the Fragment and not processed + further. +- If there are remaining Attributes, for any **inclusive** [Context Source + Registrations]{.HTML-Keyboard} that match against the remaining input data, + that input data is also forwarded for remote processing to matching endpoints + in case the Update Attributes operation is supported by the matched + registration. +- Then, implementations shall perform a partial update patch operation over the + remains of the target Entity as mandated by clause 8.4.2, using the following + procedure. +- For each Attribute (Property or Relationship) included by the Entity Fragment + at root level: + - If the target Entity does not include a matching Attribute (considering term + expansion rules as mandated by clause 8.2.4) then such Attribute shall be + appended to the target Entity. + - If the target Entity already includes a matching Attribute (considering term + expansion rules as mandated by clause 8.2.4): + - If a _`datasetId`_ is present in the Attribute included by the Entity + Fragment: + - If an Attribute instance in the target Entity has the same _`datasetId`_ + _`createdAt`_ + - If an Attribute instance in the target Entity has the same _`datasetId`_ + _`datasetId`_ + - Otherwise the Attribute instance with the specified _`datasetId`_ + + - If no _`datasetId`_ is present in the Attribute included by the Entity + Fragment, the default Attribute instance is targeted: + - If the default Attribute instance is present and the Attribute value is + not NGSI-LD Null, then the existing Attribute in the target Entity shall + be replaced by the new one supplied. The system generated _`createdAt`_ + - If the default Attribute instance is present and the Attribute value is + NGSI-LD Null, then the existing Attribute in the target Entity shall be + deleted. + - Otherwise the default Attribute instance shall be appended to the target + Entity. + +- If _`type`_ is included in the Fragment and it includes Entity Type names that + are not yet in the target Entity, add them to the list of Entity Type names of + the target Entity. +- If _`scope`_ is included in the Fragment and the target entity includes + _`scope`_, replace the scope by the one included in the Fragment, otherwise + ignore it. + +#### 10.2.3.5 Output data + +- A status code indicating whether all the new Attributes were updated or only + some of them. +- List of Attributes (Properties or Relationships) actually updated. + +### 10.2.4 Append Attributes + +#### 10.2.4.1 Description + +This operation allows modifying an NGSI-LD Entity by adding new attributes +(Properties or Relationships). + +#### 10.2.4.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can append new Attributes to an existing +Entity within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Append Attributes use case +::: + + + +#### 10.2.4.3 Input data + +- A URI representing the id of the Entity to be modified (target Entity). +- A selector of Entity types as specified by clause 7.2.2 (optional). +- A JSON-LD document representing an NGSI-LD Entity Fragment. +- An optional flag indicating whether overwriting existing Attributes within the + append operation should be permitted or denied. By default, Attribute + overwrites are permitted. + +#### 10.2.4.4 Behaviour + +The following behaviour shall be exhibited by compliant implementations: + +- If the Entity ID is not present or it is not a valid URI then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about this Entity, because there is no + existing Entity which id (URI), and where specified type, is equivalent held + locally to the one passed as a parameter, and no matching registrations apply + (see clause 9.4), an error of type [ResourceNotFound]{.HTML-Error} shall be + raised. +- The behaviour defined in clause 8.2.3 on JSON-LD validation. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the Attributes + from matching input data are forwarded for remote processing. For each + matching registration: + - If the Append Attributes operation is supported by the registration (see + clause 9), matching input data is forwarded to the Registration endpoint. + - If the Append Attributes operation is not supported by the registration, + this shall result in an error of type [Conflict]{.HTML-Error} if the + complete append failed or in a partial success if some parts of the append + succeeded. + +- The matching Attributes are then removed from the Fragment and not processed + further. +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded for + remote processing to matching endpoints in case the Append Attributes + operation is supported. +- Then, implementations shall perform an Append Attributes operation over the + remains of the target Entity as using the following procedure: + - For each Attribute (Property or Relationship) included by the Entity + Fragment at root level: + - If a _`datasetId`_ is present in the Attribute included by the Entity + Fragment: + - If no Attribute instance of the same target Entity exists that has the + same _`datasetId`_ + - If an Attribute instance of the same target Entity exists that has the + same _`datasetId`_: + - If overwrite is allowed, then the existing Attribute with the specified + _`datasetId createdAt`_ + - If overwrite is not allowed, the existing Attribute with the specified + _`datasetId`_ + + - If no _`datasetId`_ is present in the Attribute included by the Entity + Fragment: + - If no default Attribute instance of the same target Entity exists, then + such Attribute shall be appended to the target Entity. + - If a default Attribute instance of the same target Entity exists: + - If overwrite is allowed, then the existing default Attribute in the + target Entity shall be replaced by the new one supplied. The system + generated _`createdAt`_ + - If overwrite is not allowed the existing default Attribute in the target + Entity shall be left untouched. + + - If _`type`_ is included in the Fragment and it includes Entity Type names + that are not yet in the target Entity, add them to the list of Entity Type + names of the target Entity. + - If _`scope`_ is included in the Fragment and overwrite is allowed, the scope + of the target Entity will become the one included in the Fragment. + Otherwise, the Scopes in the Fragment that are not part of the value of + scope of the target Entity will be appended to the value of the _`scope`_ of + the target Entity. If there is more than one Scope, the value of _`scope`_ + is represented as a JSON array containing all Scopes. + +#### 10.2.4.5 Output data + +- A status code indicating whether all the new Attributes were appended or only + some of them. +- List of Attributes (Properties and/or Relationships) actually appended. + +### 10.2.5 Partial Attribute update + +#### 10.2.5.1 Description + +This operation allows performing a **partial update on an NGSI-LD Entity's +Attribute** (Property or Relationship). A partial update only changes the +elements provided in an Entity Fragment, leaving the rest as they are. This +operation supports the deletion of sub-Attributes but not the deletion of the +whole Attribute itself. + +#### 10.2.5.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can carry out a partial Attribute update of +an Entity within an NGSI-LD System as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Partial Attribute update use case +::: + + + +#### 10.2.5.3 Input data + +- Entity ID (URI) of the concerned Entity, the target Entity. +- A selector of Entity types as specified by clause 7.2.2 (optional). +- Target Attribute (Property or Relationship) to be modified, identified by a + name. +- A JSON-LD document representing an NGSI-LD Attribute Fragment. + +#### 10.2.5.4 Behaviour + +- If the target Entity ID is not a valid URI or it is not present, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute name is not valid or it is not present, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute is _`scope`_, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- The behaviour defined in clause 8.2.3 on JSON-LD validation. NGSI-LD Nulls + should be supported by this operation. If NGSI-LD Nulls are found in the + payload, but are not supported, an error of type + [OperationNotSupported]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI), and where specified type, is equivalent + held locally, and no matching registrations apply (see clause 9.4), then an + error of type [ResourceNotFound ]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the Attributes + from matching input data are forwarded for remote processing. For each + matching registration: + - If the Partial Attribute update operation is supported by the registration + (see clause 9), matching input data is forwarded to the Registration + endpoint. + + - If the Partial Attribute update operation is not supported by the + registration, this shall result in an error of type [Conflict]{.HTML-Error} + in case the complete partial Attribute update failed, or in a partial + success if some parts of the partial Attribute update succeeded. + + No further processing is required. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the input data, that input data is also forwarded for remote + processing to matching endpoints in case the Partial Attribute update + operation is supported. +- Apply term expansion as mandated by clause 8.2.4, so that the fully qualified + name (URI) associated to the target Attribute is properly obtained. +- If the target Entity does not contain the target Attribute: + - as a default instance in case no _`datasetId`_ is present; + - as an instance with the specified _`datasetId`_ if present; + +- then an error of type [ResourceNotFound]{.HTML-Error} + +- Perform a partial update patch operation on the target Attribute following the + algorithm mandated by clause 8.4.2 If present in the provided NGSI-LD Entity + Fragment, the type of the Attribute has to be the same as the type of the + targeted Attribute fragment, i.e. it is not allowed to change the type of an + Attribute. + +#### 10.2.5.5 Output data + +None. + +### 10.2.6 Set Attribute Value + +#### 10.2.6.1 Description + +#### 10.2.6.2 Use case diagram + +#### 10.2.6.3 Input data + +#### 10.2.6.4 Behaviour + +#### 10.2.6.5 Output data + +### 10.2.7 Delete Attribute + +#### 10.2.7.1 Description + +This operation allows deleting an NGSI-LD Attribute (Property or Relationship). +The Attribute itself and all its children shall be deleted. + +#### 10.2.7.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can delete a specific Attribute within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Attribute use case +::: + + + +#### 10.2.7.3 Input data + +- Entity ID (URI) of the concerned Entity, the target Entity. +- A selector of Entity types as specified by clause 7.2.2 (optional). +- Target Attribute (Property or Relationship) to be deleted, identified by a + name. +- An optional parameter identifying the _`datasetId`_ of the target Attribute + instance to be deleted. Otherwise the default Attribute instance is targeted. +- An optional flag _`deleteAll`_ indicating whether also all target Attribute + instances with a _`datasetId`_ are to be deleted. +- An optional JSON-LD _`@context`_. + +#### 10.2.7.4 Behaviour + +- If the target Entity ID is not a valid URI or it is not present, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute name is not a valid name or it is not present, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the input data + (see clause 9.4), the input data is forwarded. For each matching registration: + - If the Delete Attribute operation is supported by the registration (see + clause 9), matching input data is forwarded to the Registration endpoint. + - If the Delete Attribute update operation is not supported by the matched + registration, this shall result in an error of type [Conflict]{.HTML-Error} + in case the complete delete Attribute failed, or in a partial success if + some parts of the delete Attribute succeeded. + +- No further processing is required. + +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI), and where specified type, is equivalent + held locally, and no matching registrations apply, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the input data, that input data is also forwarded for remote + processing to matching endpoints in case the Delete Attribute operation is + supported by the matched registration. +- Apply term expansion as mandated by clause 8.2.4 so that the fully qualified + name (URI) associated to the target Attribute is properly obtained. +- If the target Entity does not contain the target Attribute then an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- If the target Attribute is _`scope`_, remove the _`scope`_ Attribute from the + target Entity. +- If the _`deleteAll`_ flag is set, remove all target Attribute instances from + the target Entity. +- Otherwise: + - if a _`datasetId`_ parameter is provided, remove only the target Attribute + instance from the given dataset whose _`datasetId`_ matches the parameter; + - if no _`datasetId`_ parameter is provided, remove the default target + Attribute instance from the target Entity. + +#### 10.2.7.5 Output data + +None. + +### 10.2.8 Delete Entity + +#### 10.2.8.1 Description + +This operation allows deleting an NGSI-LD Entity. + +#### 10.2.8.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can completely delete an Entity within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Entity use case +::: + + + +#### 10.2.8.3 Input data + +- Entity ID (URI) of the Entity to be deleted, the target Entity. +- A selector of Entity types as specified by clause 7.2.2 (optional). + +#### 10.2.8.4 Behaviour + +- If the target Entity ID is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI), and where specified type, is equivalent + held locally, and no matching registrations apply (see clause 9.4), then an + error of type [ResourceNotFound ]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the id, the request is forwarded + for remote processing. For each matching registration: + - If the Delete Entity operation is supported by the registration (see clause + 9), the request is forwarded to the Registration endpoint. + - If the Delete Entity update operation is not supported by the matched + registration, this shall result in an error of type [Conflict]{.HTML-Error} + in case the complete delete Entity failed, or in a partial success if some + parts of the delete Entity succeeded. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded in + the case the Delete Entity operation is supported for remote processing by + matching endpoints. +- The input data shall be used to remove the entity locally if it exists. + +#### 10.2.8.5 Output data + +None. + +### 10.2.9 Merge Entity + +#### 10.2.9.1 Description + +This operation allows modification of an existing NGSI-LD Entity aligning to the +JSON Merge Patch processing rules defined in IETF RFC 7396 [n.17] by adding new +Attributes (Properties or Relationships) or modifying or deleting existing +Attributes associated with an existing Entity. + +#### 10.2.9.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can perform a merge on an Entity within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Merge Entity use case +::: + + + +#### 10.2.9.3 Input data + +- A URI representing the id of the Entity to be merged (target Entity). +- A selector of Entity types as specified by clause 7.2.2 (optional). +- A JSON-LD document representing an NGSI-LD Entity Fragment. +- An optional flag indicating whether the JSON-LD document contains a simplified + representation of the entity. +- An optional parameter indicating a common _`observedAt`_ timestamp to use + across merged Attributes. +- An optional parameter representing a common IETF RFC 5646 [n.11] language tag + to use across merged LanguageMap Attributes. + +#### 10.2.9.4 Behaviour + +The following behaviour shall be exhibited by compliant implementations: + +- If the Entity ID is not present or it is not a valid URI then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI), and where specified type, is equivalent + held locally, and no matching registrations apply (see claue 9.4), then an + error of type [ResourceNotFound]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, Attributes from + matching input data are forwarded. For each matching registration: + - If the Merge Entity operation is supported by the matched registration (see + clause 9), matching input data is forwarded to the Registration endpoint. + - If the Merge Entity operation is not supported by the matched registration, + this shall result in an error of type [Conflict]{.HTML-Error} in case the + complete Merge Entity operation failed, or in a partial success if some + parts of it succeeded. + +- The matching Attributes are then removed from the Fragment and not processed + further. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded in + the case the Merge Entity operation is supported for remote processing to + matching endpoints. +- The behaviour defined in clause 8.2.3 on JSON-LD validation. NGSI-LD Nulls + should be supported by this operation. If NGSI-LD Nulls are found in the + payload, but are not supported, an error of type + [OperationNotSupported]{.HTML-Error} shall be raised. + +- Then, implementations shall perform a merge operation over the target Entity + as mandated by clause 8.4.3, using the following procedure: +- For each Attribute (Property or Relationship) included by the Entity Fragment: + - If the target Entity does not include a matching Attribute (considering term + expansion rules as mandated by clause 8.2.4), then such Attribute shall be + appended to the target Entity. + - If the target Entity already includes a matching Attribute (considering term + expansion rules as mandated by clause 8.2.4): + - If the Attribute (Property or Relationship) to be merged is represented in + a simplified representation, the _`type`_ of any pre-existing Attribute in + the target entity shall be preserved. + - If a common language tag is defined and a _LanguageProperty_ Attribute to + be merged is represented as a string, the pre-existing _`languageMap`_ + JSON object shall be preserved. The string value shall only replace the + value associated to the language tag key found within the _`languageMap`_. + - If a common _`observedAt`_ timestamp is defined and an existing Attribute + to be merged previously contained an _`observedAt`_ sub-Attribute, the + _`observedAt`_ sub-Attribute is also updated using the common timestamp, + unless the Entity Fragment itself contains an explicit updated value for + the _`observedAt`_ sub-Attribute. + - If a _`datasetId`_ is present in the Attribute included by the Entity + Fragment: + - If an Attribute instance in the target Entity has the same*`datasetId`* + - If overwrite is allowed and the Attribute value is not NGSI-LD Null, + then the existing Attribute with the specified*`datasetId`* + - If overwrite is allowed and the Attribute value is NGSI-LD Null, then + the existing Attribute with the specified*`datasetId`* + - If overwrite is not allowed, the existing Attribute with the + specified*`datasetId`* + + - Otherwise the Attribute instance with the specified*`datasetId`* + + - If no _`datasetId`_ is present in the Attribute included by the Entity + Fragment, the default Attribute instance is targeted: + - If the default Attribute instance is present: + - If overwrite is allowed and the Attribute value is not NGSI-LD Null, + then the existing Attribute in the target Entity shall be merged with + the new one supplied. + - If overwrite is allowed and the Attribute value is NGSI-LD Null, then + the existing Attribute with the specified*`datasetId`* + - If overwrite is not allowed, the existing Attribute in the target + Entity shall be left untouched. + + - Otherwise if value is not NGSI-LD Null, the default Attribute instance + shall be appended to the target Entity. + +- If _`type`_ is included in the Fragment and it includes Entity Type names that + are not yet in the target Entity, add them to the list of Entity Type names of + the target Entity. +- If _`scope`_ is included in the Fragment and overwrite is allowed, the scope + of the target Entity will become the one included in the Fragment. Otherwise, + the Scopes in the Fragment that are not part of the value of _`scope`_ of the + target Entity will be appended to the value of the _`scope`_ of the target + Entity. If there is more than one Scope, the value of _`scope`_ is represented + as a JSON array containing all Scopes. + +#### 10.2.9.5 Output data + +- A status code indicating whether all the Attributes were merged successfully. +- List of Attributes (Properties and/or Relationships) actually merged. + +### 10.2.10 Replace Entity + +#### 10.2.10.1 Description + +This operation allows the modification of an existing NGSI-LD Entity by +replacing all of the Attributes (Properties or Relationships). + +#### 10.2.10.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can replace an entire Entity within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Replace Entity use case +::: + + + +#### 10.2.10.3 Input data + +- A URI representing the id of the Entity to be replaced (target Entity). +- A selector of Entity types as specified by clause 7.2.2 (optional). +- A JSON-LD document representing an NGSI-LD Entity. + +#### 10.2.10.4 Behaviour + +- If the target Entity ID is not a valid URI or it is not present, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI), and where specified type, is equivalent + held locally, and no matching registrations apply (see clause 9.4), then an + error of type [ResourceNotFound]{.HTML-Error} shall be raised. +- The behaviour defined in clause 8.2.3 on JSON-LD validation. NGSI-LD Nulls are + not supported by this operation. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, Attributes from + matching input data are forwarded. For each matching registration: + - If the Replace Entity operation is supported by the registration (see clause + 9), matching input data is forwarded to the Registration endpoint. + - If the Replace Entity operation is not supported by the registration, this + shall result in an error of type [Conflict]{.HTML-Error} in case the + complete Replace Entity operation failed, or in a partial success if some + parts of it succeeded. + +- The matching Attributes are then removed from the Fragment and not processed + further. +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded in + the case the Replace Entity operation is supported for remote processing to + matching endpoints. +- If the target Entity exists locally, completely replace the existing Entity + with the same Entity ID with the new Entity content provided. The system + generated _`createdAt`_ Temporal Property of the Entity as defined in clause + 5.2.4 remain unchanged. + +#### 10.2.10.5 Output data + +None. + +### 10.2.11 Replace Attribute + +#### 10.2.11.1 Description + +This operation allows the replacement of a single Attribute (Property or +Relationship) within an NGSI-LD Entity. + +#### 10.2.11.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can carry out a replacement of an Attribute +within an Entity within an NGSI-LD System as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Replace Attribute use case +::: + + + +#### 10.2.11.3 Input data + +- Entity ID (URI) of the concerned Entity, the target Entity. +- A selector of Entity types as specified by clause 7.2.2 (optional). +- Target Attribute (Property or Relationship) to be replaced, identified by a + name. +- A JSON-LD document representing an NGSI-LD Attribute Fragment. + +#### 10.2.11.4 Behaviour + +- If the target Entity ID is not a valid URI, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute name is not valid, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute is _`scope`_, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI), and where specified type, is equivalent + held locally, and no matching registrations apply (see clause 9.4), then an + error of type [ResourceNotFound]{.HTML-Error} shall be raised. +- The behaviour defined in clause 8.2.3 on JSON-LD validation. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the input data + is forwarded. For each matching registration: + - If the Replace Attribute operation is supported by the registration (see + clause 9), matching input data is forwarded to the Registration endpoint. + - If the Replace Attribute operation is not supported by the registration, + this shall result in an error of type [Conflict]{.HTML-Error} in case the + complete Replace Attribute operation failed, or in a partial success if some + parts of it succeeded. + +- No further processing is required. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded in + the case the Replace Attribute operation is supported for remote processing to + matching endpoints. +- Apply term expansion as mandated by clause 8.2.4, so that the fully qualified + name (URI) associated to the target Attribute is properly obtained. +- If the target Entity does not contain the target Attribute: + +- as a default instance in case no _`datasetId`_ is present; +- as an instance with the specified _`datasetId`_ if present; +- then this shall result in an error of type [ResourceNotFound]{.HTML-Error} in + case the complete Replace Attribute operation failed, or in a partial success + if some parts of it succeeded. + +- Completely replace the existing Attribute instance with the new Attribute + content provided. The system generated _`createdAt`_ Temporal Property as + defined in clause 5.2.4 remains unchanged. + +#### 10.2.11.5 Output data + +None. + +### 10.2.12 Purge Entities + +#### 10.2.12.1 Description + +This operation allows the deletion of entities within an NGSI-LD system based +upon a query. + +#### 10.2.12.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can delete a set of entities which matches +a specific query from an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Purge Entities use case +::: + + + +#### 10.2.12.3 Input data + +- A reference to a JSON-LD _`@context`_ (optional). +- A selector of Entity types as specified by clause 7.2.2 (optional). Both type + names (short hand string) and fully qualified type names (URI) are allowed in + the selector. +- A list (one or more) of Entity identifiers (optional). +- A restrictive list of Attribute names to be deleted as attributes (optional). +- An exclusionary list Attribute names to be kept as attributes (optional). +- An id pattern as a regular expression (optional). +- An NGSI-LD query (to filter out Entities by Attribute values) as per clause + 7.2.3 (optional). +- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as + mandated by clause 7.2.4 (optional). +- A NGSI-LD Scope query (to filter out Entities based on their Scope) as + mandated by clause 7.2.5 (optional). +- An NGSI-LD query (called context source filter, to filter out [Context + Sources]{.HTML-Keyboard} by the values of properties that describe them) as + per clause 7.2.3 (optional). + +In the general case, it is not possible to purge a set of entities by only +specifying desired Entity identifiers, without further specifying restrictions +on the entities' types or attributes, either explicitly, via selector of Entity +types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. +If the execution of the operation is limited to the local scope (see clause +8.6), no further restrictions have to be provided. + +#### 10.2.12.4 Behaviour + +- At least one of the following input data shall be provided: + + + + a. selector of Entity Types; + b. list of Attribute names, including at least one non-system Attribute; + c. NGSI-LD Query, including at least one non-system Attribute; + d. NGSI-LD GeoQuery; + e. local scope (see clause 8.6). + + + +- If none of the above is provided, then an error of type + [BadRequestData]{.HTML-Error} + +- If the list of Entity identifiers includes a URI which it is not valid, or the + query, geoquery or context source filter are not syntactically valid (as per + the referred clauses 7.2.3 and 7.2.4) an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If projection attributes are present and indicate the use of [Linked Entity + ]{.HTML-Keyboard} retrieval, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the filter conditions specified by the query includes [Linked + Entity]{.HTML-Keyboard} attributes then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- Term to URI expansion of type and Attribute names shall be performed, as + mandated by clause 8.2.4. +- Otherwise, implementations shall run a Query Entities operation (clause + 10.4.3) to retrieve a list of ids of Entities for deletion, that meet all of + the following conditions (given the respective parameter is provided): + +- id is equal to any of the id(s) passed as a parameter; +- the Entity Type names match the selector of Entity Types (expanded) that is + passed as a parameter; +- Attribute matches any of the expanded attribute(s) in the list that is passed + as a parameter; +- id matches the id pattern passed as a parameter; +- the filter conditions specified by the query are met (as mandated by clause + 7.2.3); +- the geospatial restrictions imposed by the geoquery are met (as mandated by + clause 7.2.4); if there are multiple instances of the GeoProperty on which the + geoquery is based, it is sufficient if any of these instances meets the + geospatial restrictions; +- if the Scope query is present, it shall match a present Entity Scope (as + mandated by clause 7.2.5, for an example see annex C, clause C.5.15). + +- And thereafter: + - when no restrictive list of Entity member names is present, the + implementation shall delete all Entities that can be found locally using + retrieved list of Entity ids; + - when a restrictive list of Entity member names is present, the + implementation shall delete the given set of Attributes with those member + names from all Entities that can be found locally using retrieved list of + Entity ids; + - when an exclusionary list of Entity member names is present, the + implementation shall delete all but the given set of Attributes with those + member names from all Entities that can be found locally using retrieved + list of Entity ids. + +- Unless local scope is specified (see clause 8.6), for [Context Source + Registrations]{.HTML-Keyboard} that match the query and support the + "purgeEntity" operation (see operations and operation groups in clause 9.2), + implementations shall do the following: +- If an **inclusive,** **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the filter conditions specified, + the request is forwarded for remote processing. For each matching + registration: + - If the Purge Entity operation is supported by the registration (see clause + 9), matching input data is forwarded to the Registration endpoint. + - If the Purge Entity operation is not supported by the matched registration, + this shall result in an error of type [Conflict]{.HTML-Error} in case the + complete purge Entities failed, or in a partial success if some parts of + purge Entities succeeded. + +#### 10.2.12.5 Output data + +None. + +## 10.3 Context information provision - batch operations + +### 10.3.1 Introduction + +Clause 10.3 specifies a set of batch operations that allow handling multiple +Entities in a single request. The operations defined are: + +- Batch Entity creation (clause 10.3.2) +- Batch Entity creation or update (upsert) (clause 10.3.3) +- Batch Entity update (clause 10.3.4) +- Batch Entity merge (clause 10.3.5) +- Batch Entity delete (clause 10.3.6) + +It is allowed for such an input Entity array to contain more than one instance +of the same entity (those instances have identical ids). + +In order for such a request to be correctly handled, those instances that have +the same [id]{.HTML-Variable} are processed by the Broker in the order they have +in the array: the higher the index in the array, the later it will be processed. +If the order is altered, the outcome may be altered. Without this assumption, +there is no way for the request to be treated correctly, as the entity instances +are often used for replacing or modifying the prior entity instance. + +All Entities and Attributes in the batch will get the same +[modifiedAt]{.HTML-Variable} timestamp, so it makes sense to distinguish them +via the [observedAt]{.HTML-Variable} temporal property. + +Implementations shall treat the entity instances as if they had all arrived in +separate requests. + +The following clauses specify the behaviour in each case. + +### 10.3.2 Batch Entity creation + +#### 10.3.2.1 Description + +This operation allows creating a batch of NGSI-LD Entities. + +#### 10.3.2.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can create a batch of NGSI-LD Entities +within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Create a batch of Entities use case +::: + + + +#### 10.3.2.3 Input data + +- A JSON-LD Array containing one or more JSON-LD documents each one representing + an NGSI-LD Entity as mandated by clause 5.2.6.4.1. + +#### 10.3.2.4 Behaviour + +Implementations shall exhibit the following behaviour: + +- If the input Array is empty or contains a [null]{.HTML-Variable} value in any + of its items an error of type [BadRequestData]{.HTML-Error} shall be raised. +- Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. +- Let S be an array which shall contain a list of Entity IDs, one for each + NGSI-LD Entity successfully created. S shall be initialized to the empty + array. +- Let E be an array which shall contain a list of + [BatchEntityError]{.HTML-Error} as defined by clause 5.2.6.8.2, one for each + NGSI-LD Entity which resulted in error. E shall be initialized to the empty + array. +- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context + Registry]{.HTML-Keyboard}: + - Let IN be a copy of the original input array. + - Remove from IN all Entities not matched by CSR and remove non-matching + Attributes from the remaining Entities. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **exclusive** [Context Source Registration]{.HTML-Keyboard}, which + is not CSR itself. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **redirect** [Context Source Registration]{.HTML-Keyboard}, unless + CSR is a redirect [Context Source Registration]{.HTML-Keyboard} itself. + - If IN is empty, continue with the next [Context Source + Registration]{.HTML-Keyboard} if there is any. + - If the Batch Entity Creation operation is supported by CSR: + - Forward the Batch Entity Creation request with IN as input Array. + - Merge the returned list of Entities successfully created with S. + - Merge the returned list of Entities in Error with E. + + - Otherwise, if the Create Entity operation (clause 10.2.2) is supported by + CSR: + - For each Entity EN in the input array: + - Forward a Create Entity request for Entity EN. + - Merge any successful result(s) for Entity EN created with S. + - Merge any error result(s) for Entity EN created with E. + + - Otherwise: + - In case CSR is an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard}, add an Error of type + [Conflict]{.HTML-Error} for each Entity in IN to E. + +- For each of the NGSI-LD Entities included in the input Array execute the + behaviour defined by clause 10.2.2, but limited to a local operation, as + follows: + - If the Entity was successfully created, then add the corresponding Entity ID + to the S array. + - If the Entity creation failed, then a new [BatchEntityError]{.HTML-Error} + shall be added to E containing the failed Entity ID and the related + [ProblemDetails]{.HTML-Definition}. + - In case of multiple instances of the same Entity ID, if the Entity + corresponding to an Entity ID was successfully created in the first + occurrence, then for all subsequent occurrences the error + [AlreadyExists]{.HTML-Error} shall be added to E containing the failed + Entity ID and the related [ProblemDetails]{.HTML-Definition}. + +#### 10.3.2.5 Output data + +- The list of Entities successfully created (S Array), if all Entities were + created correctly; or +- the list of Entities successfully created (S Array) and the list of Entities + in error (E Array), if only some or none of the Entities were created. + +### 10.3.3 Batch Entity creation or update (upsert) + +#### 10.3.3.1 Description + +This operation allows creating a batch of NGSI-LD Entities, updating each of +them if they already existed. In some database jargon this kind of operation is +known as "upsert". + +#### 10.3.3.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can create or update a batch of Entities +within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Upsert a batch of Entities use case +::: + + + +#### 10.3.3.3 Input data + +- A JSON-LD Array containing one or more JSON-LD documents each one representing + an Entity as mandated by clause 5.2.6.4.1. +- An optional flag indicating the update mode (only applies in case the Entity + already exists): + - Replace. All the existing Entity content shall be replaced (default mode). + - Update. Existing Entity content shall be updated. + + +>>> [!note] + +In case of multiple instances of the same entity, these replace +or update operations are processed **in chronological order.** + +>>> + + +#### 10.3.3.4 Behaviour + +Implementations shall exhibit the following behaviour: + +- If the input Array is empty or contains a [null]{.HTML-Variable} value in any + of its items, an error of type [BadRequestData]{.HTML-Error} shall be raised. +- Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. +- Let S be an array which shall contain a list of Entity IDs, one for each + NGSI-LD Entity which was successfully processed. S shall be initialized to the + empty array. +- Let E be an array which shall contain a list of + [BatchEntityError]{.HTML-Error} as defined by clause 5.2.6.8.2, one for each + NGSI-LD Entity which resulted in error. E shall be initialized to the empty + array. +- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context + Registry]{.HTML-Keyboard}: + - Let IN be a copy of the original input array. + - Remove from IN all Entities not matched by CSR and remove non-matching + Attributes from the remaining Entities. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **exclusive** [Context Source Registration]{.HTML-Keyboard}, which + is not CSR itself. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **redirect** [Context Source Registration]{.HTML-Keyboard}, unless + CSR is a redirect [Context Source Registration]{.HTML-Keyboard} itself. + - If IN is empty, continue with the next [Context Source + Registration]{.HTML-Keyboard} if there is any. + - If the Batch Entity Creation or Update (Upsert) operation is supported by + CSR: + - Forward the Batch Entity Creation or Update (Upsert) request with IN as + input Array. + - Merge the returned list of Entities successfully created with S. + - Merge the returned list of Entities in Error with E. + + - Otherwise, if the Create Entity operation (clause 10.2.2) is supported by + CSR: + - For each Entity EN in the input array: + - Forward a Create Entity request for Entity EN. + - If an error of type[AlreadyExists]{.HTML-Error} is returned: + - If the Replace Entity operation (clause 10.2.28) is supported by CSR + and the value of the update mode flag is Replace or the flag is not + set, forward a Replace Entity request for Entity EN. + - Otherwise, if the Update Attributes operation (clause 10.2.3) is + supported by CSR and the value of the update mode flag is Update, + forward an Update Attributes request for Entity EN. + - Otherwise add an OperationNotSupported Error for Entity EN related to + CSR to E. + + - Merge any successful result(s) for Entity EN created or updated with S. + - Merge any error result(s) for Entity EN created or updated with E. + + - Otherwise, if the Replace Entity operation (clause 10.2.28) is supported by + CSR and the value of the update mode flag is Replace or the flag is not set: + - Forward a Replace Entity request for Entity EN. + - Merge any successful result(s) for Entity EN updated with S. + - Merge any error result(s) for Entity EN updated with E. + + - Otherwise, if the Update Attributes operation (clause 10.2.3) is supported + by CSR and the value of the update mode flag is Update: + - Forward an Update Attributes request for Entity EN. + - Merge any successful result(s) for Entity EN updated with S. + - Merge any error result(s) for Entity EN updated with E. + + - Otherwise: + - In case CSR is an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard}, add an Error of type + [Conflict]{.HTML-Error} for each Entity in IN to E. + +- For each of the NGSI-LD Entities included in the input Array implementations + shall: + - Create the Entity locally if it does not exist (i.e. no Entity with the same + Entity ID is present) executing the behaviour defined by clause 10.2.2, but + limited to a local operation. In case of multiple instances of the same + entity in the input array, only the first occurrence will shall lead to its + creation. + - If there were an existing Entity with the same Entity ID, it shall be + completely replaced by the new Entity content provided, if the requested + update mode is 'replace'. + - If there were an existing Entity with the same Entity ID, the behaviour + defined by clause 10.2.3 shall be executed, but limited to a local + operation, if the requested update mode is ["update"]{.HTML-Code}. + +- If successful, the local creation or update shall be added to S. If while + processing an Entity there is any kind of error or abnormal situation, a + [BatchEntityError]{.HTML-Error} shall be added to E containing the failed + Entity ID and the related [ProblemDetails]{.HTML-Definition}. + +#### 10.3.3.5 Output data + +- none (if all Entities already existed and are successfully updated); or +- the list of Entities successfully created (S Array), if all Entities not + existing prior to this request have been successfully created and the others + have been successfully updated; or +- the list of Entities successfully created or updated (S Array), and the list + of Entities in error (E Array), if only some or none of the Entities have been + successfully created or updated. + +### 10.3.4 Batch Entity update + +#### 10.3.4.1 Description + +This operation allows updating a batch of NGSI-LD Entities. + +#### 10.3.4.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can update a batch of Entities within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Update a batch of Entities use case +::: + + + +#### 10.3.4.3 Input data + +- A JSON-LD Array containing one or more JSON-LD documents each one representing + an Entity as mandated by clause 5.2.6.4.1. +- An optional flag indicating whether Attributes shall be overwritten or not. By + default, Attributes will be overwritten. + + +>>> [!note] + +In case of multiple instances of the same entity, these append +or update operations are processed **in chronological order.** + +>>> + + +#### 10.3.4.4 Behaviour + +Implementations shall exhibit the following behaviour: + +- If the input Array is empty or contains a [null]{.HTML-Variable} value in any + of its items, an error of type [BadRequestData]{.HTML-Error} shall be raised. +- Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. +- Let S be an array which shall contain a list of Entity IDs, one for each + NGSI-LD Entity which was successfully processed. S shall be initialized as the + empty array. +- Let E be an array which shall contain a list of + [BatchEntityError]{.HTML-Error} as defined by clause 5.2.6.8.2, one for each + NGSI-LD Entity which resulted in error. E shall be initialized as the empty + array. +- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context + Registry]{.HTML-Keyboard}: + - Let IN be a copy of the original input array. + - Remove from IN all Entities not matched by CSR and remove non-matching + Attributes from the remaining Entities. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **exclusive** [Context Source Registration]{.HTML-Keyboard}, which + is not CSR itself. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **redirect** [Context Source Registration]{.HTML-Keyboard}, unless + CSR is a redirect [Context Source Registration]{.HTML-Keyboard} itself. + - Remove all Entities without Attributes from IN. + - If IN is empty, continue with the next [Context Source + Registration]{.HTML-Keyboard} if there is any. + - If the Batch Entity Update operation is supported by CSR: + - Forward the Batch Entity Update request with IN as input Array. + - Merge the returned list of Entities successfully created with S. + - Merge the returned list of Entities in Error with E. + + - Otherwise, if the Update Attributes operation (clause 10.2.3) is supported + by CSR and Attribute overwrite is permitted: + - For each Entity EN in the input array: + - Forward an Update Attributes request for Entity EN. + - Merge any successful result(s) for Entity EN updated with S. + - Merge any error result(s) for Entity EN updated with E. + + - Otherwise, if the Append Attributes operation (clause 10.2.4) is supported + by CSR and Attribute overwrite is not permitted: + - For each Entity EN in the input array: + - Forward an Append Attributes request for Entity EN with Attribute + overwrite disabled: + - Merge any successful result(s) for Entity EN updated with S. + - Merge any error result(s) for Entity EN updated with E. + + - Otherwise: + - In case CSR is an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard}, add an Error of type + [Conflict]{.HTML-Error} for each Entity in IN to E. + +- For each of the NGSI-LD Entities included in the input Array execute the + behaviour defined by clause 10.2.4, but limited to a local operation, as + follows: + - If the Entity was successfully updated (Attributes appended), then add the + corresponding Entity ID to the S array. + - If the Entity update failed, then a new [BatchEntityError]{.HTML-Error} + shall be added to E containing the failed Entity ID and the + [ProblemDetails]{.HTML-Definition} associated. + +#### 10.3.4.5 Output data + +- none (if all Entities are successfully updated); or +- the list of Entities successfully updated (S Array), and the list of Entities + in error (E Array), if only some or none of the Entities have been + successfully updated. + +### 10.3.5 Batch Entity merge + +#### 10.3.5.1 Description + +This operation allows modification of a batch of NGSI-LD Entities according to +the JSON Merge Patch processing rules defined in IETF RFC 7396 [n.17] by adding +new attributes (Properties or Relationships) or modifying or deleting existing +attributes associated with an existing Entity. + +#### 10.3.5.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can merge a batch of Entities within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Merge a batch of Entities use case +::: + + + +#### 10.3.5.3 Input data + +- A JSON-LD Array containing one or more JSON-LD documents each one representing + an Entity as mandated by clause 5.2.6.4.1. + + +>>> [!note] + +In case of multiple instances of the same entity, merge operations are processed **in chronological order.** + +>>> + + +#### 10.3.5.4 Behaviour + +Implementations shall exhibit the following behaviour: + +- Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. +- Let S be an array which shall contain a list of Entity IDs, one for each + NGSI-LD Entity which was successfully processed. S shall be initialized as the + empty array. +- Let E be an array which shall contain a list of + [BatchEntityError]{.HTML-Error} as defined by clause 5.2.6.8.2, one for each + NGSI-LD Entity which resulted in error. E shall be initialized as the empty + array. +- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context + Registry]{.HTML-Keyboard}: + - Let IN be a copy of the original input array. + - Remove from IN all Entities not matched by CSR and remove non-matching + Attributes from the remaining Entities. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **exclusive** [Context Source Registration]{.HTML-Keyboard}, which + is not CSR itself. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **redirect** [Context Source Registration]{.HTML-Keyboard}, unless + CSR is a redirect [Context Source Registration]{.HTML-Keyboard} itself. + - Remove all Entities without Attributes from IN. + - If IN is empty, continue with the next [Context Source + Registration]{.HTML-Keyboard} if there is any. + - If the Batch Entity Merge operation is supported by CSR: + - Forward the Batch Entity Merge request with IN as input Array. + - Merge the returned list of Entities successfully created with S. + - Merge the returned list of Entities in Error with E. + + - Otherwise, if the Merge Entity operation (clause 10.2.27) is supported by + CSR: + - For each Entity EN in the input array: + - Forward a Merge Entity request for Entity EN. + - Merge any successful result(s) for Entity EN merged with S. + - Merge any error result(s) for Entity EN merged with E. + + - Otherwise: + - In case CSR is an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard}, add an Error of type Conflict for each + Entity in IN to E. + +- For each of the NGSI-LD Entities included in the input Array execute the + behaviour defined by clause 10.2.27, but limited to a local operation, as + follows: + - If the Entity was successfully merged (Attributes updated, appended or + deleted), then add the corresponding Entity ID to the S array. + - If the Entity merge failed, then a new [BatchEntityError]{.HTML-Error} shall + be added to E containing the failed Entity ID and the + [ProblemDetails]{.HTML-Definition} associated. + +#### 10.3.5.5 Output data + +- none (if all Entities already existed and are successfully merged); or +- the list of Entities successfully merged (S Array), and the list of Entities + in error (E Array), if only some or none of the Entities have been + successfully merged. + +### 10.3.6 Batch Entity delete + +#### 10.3.6.1 Description + +This operation allows deleting a batch of NGSI-LD Entities. + +#### 10.3.6.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can delete a batch of Entities within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete a batch of Entities use case +::: + + + +#### 10.3.6.3 Input data + +- A JSON-LD Array containing a list of Entity IDs (URIs) that are requested to + be deleted. + +#### 10.3.6.4 Behaviour + +Implementations shall exhibit the following behaviour: + +- If the input Array is empty or contains a [null]{.HTML-Variable} value in any + of its items, an error of type [BadRequestData]{.HTML-Error} shall be raised. +- Let S be an array which shall contain a list of Entity IDs, one for each + NGSI-LD Entity which was successfully processed. S shall be initialized to the + empty array. +- Let E be an array which shall contain a list of + [BatchEntityError]{.HTML-Error} as defined by clause 5.2.6.8.2, one for each + NGSI-LD Entity which resulted in error. E shall be initialized to the empty + array. +- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context + Registry]{.HTML-Keyboard}: + - Let IN be a copy of the original input array. + - Remove from IN all Entities not matched by CSR and remove non-matching + Attributes from the remaining Entities. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **exclusive** [Context Source Registration]{.HTML-Keyboard}, which + is not CSR itself. + - Remove all Attributes from the remaining Entities in IN for which there is a + matching **redirect** [Context Source Registration]{.HTML-Keyboard}, unless + CSR is a redirect [Context Source Registration]{.HTML-Keyboard} itself. + - Remove all Entities without Attributes from IN. + - If IN is empty, continue with the next [Context Source + Registration]{.HTML-Keyboard} if there is any. + - If the Batch Entity Delete operation is supported by CSR: + - Forward the Batch Entity Delete request with IN as input Array. + - Merge the returned list of Entities successfully created with S. + - Merge the returned list of Entities in Error with E. + + - Otherwise, if the Delete Entity operation (clause 10.2.8) is supported by + CSR: + - For each Entity EN in the input array: + - Forward a Delete Entity request for Entity EN. + - Merge any successful result(s) for Entity EN deleted with S. + - Merge any error result(s) for Entity EN deleted with E. + + - Otherwise: + - In case CSR is an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard}, add an Error of type + [Conflict]{.HTML-Error} for each Entity in IN to E. + - For each of the NGSI-LD Entity IDs included in the input Array execute the + behaviour defined by clause 10.2.8, but limited to a local operation, as + follows: + - If the Entity corresponding to an Entity ID was successfully deleted, + then add such Entity ID to the S array. + - If the Entity deletion failed, then a new + [BatchEntityError]{.HTML-Error} shall be added to E containing the + failed Entity ID and the related [ProblemDetails]{.HTML-Definition}. + - In case of multiple instances of the same Entity ID, if the Entity + corresponding to an Entity ID was successfully deleted in the first + occurrence, then for all subsequent occurrences the error + [ResourceNotFound]{.HTML-Error} shall be added to E containing the + failed Entity ID and the related [ProblemDetails]{.HTML-Definition}. + +#### 10.3.6.5 Output data + +- none (if all Entities that already existed are successfully deleted); or +- the list of Entities successfully deleted (S Array), and the list of Entities + in error (E Array), if some or all of the Entities have not been successfully + deleted. + +## 10.4 Context information consumption + +### 10.4.1 Introduction + +Clause 10.4 defines the operations that allow [Context +Consumers]{.HTML-Keyboard} to retrieve context information from an NGSI-LD +system. + +### 10.4.2 Retrieve Entity + +#### 10.4.2.1 Description + +This operation allows retrieving an NGSI-LD Entity. + +#### 10.4.2.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve a specific Entity from an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Entity use case +::: + + + +#### 10.4.2.3 Input data + +- Entity ID (URI) of the Entity to be retrieved (target Entity). +- A selector of Entity types as specified by clause 7.2.2 (optional). +- List of Attribute (_Properties_ or _Relationships_) names to be retrieved + (projection attributes) (optional). +- A restrictive list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + retrieved (projection attributes as defined by clause 7.3.2) (optional). +- An exclusionary list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + removed (projection attributes as defined by clause 7.3.2) (optional). +- A language filter as defined by clause 7.2.7 (optional). +- An optional JSON-LD context. +- In the case of a GeoJSON representation, the name of the _GeoProperty_ + attribute to use as the geometry for the GeoJSON representation as mandated by + clause 5.3.3 (optional). +- An optional flag indicating whether to include additional [Linked + Entities]{.HTML-Keyboard} corresponding to the _Relationships_ retrieved and + how to format those [Linked Entities]{.HTML-Keyboard}. See clause 7.7 + (optional). +- A limit to the depth of [Linked Entities]{.HTML-Keyboard} to search whilst + traversing an Entity graph. See clause 7.7 (optional). +- A list (one or more) of [Linked Entity]{.HTML-Keyboard} identifiers previously + encountered whilst traversing an Entity graph. See clause 7.7 (optional). +- A flag indicating whether to return the location of the [Entity + Map]{.HTML-Keyboard} used within the operation (optional). +- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity + Map]{.HTML-Keyboard} is to be created (optional). +- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching + Entity registrations (optional). +- A _`datasetId`_ parameter that specifies which Attribute instances are to be + selected as defined by clause 8.5 (optional). + +#### 10.4.2.4 Behaviour + +- If the Entity ID is not present or it is not a valid URI, then an error of + type [BadRequestData]{.HTML-Error} shall be raised. +- If geometryProperty parameter is present and the Accept Header is not set to + ["application/geo+json"]{.HTML-Code}, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If projection attributes are present and indicate the use of [Linked Entity + ]{.HTML-Keyboard} retrieval and the use of [Linked Entity ]{.HTML-Keyboard} + retrieval is not specified, or the projected attribute depth exceeds the + [Linked Entity ]{.HTML-Keyboard} retrieval depth, an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity held locally whose id (URI), and where specified type, + is equivalent, and no matching registrations apply, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- The implementation shall retrieve any Attribute data held locally which is + associated with the Entity defined by the Entity ID. +- If the ContextBroker implementation supports the use of [Entity + Maps]{.HTML-Keyboard} then: + - If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of + matching Entity registrations is present it shall be retrieved: + - If the resource cannot be found, or the data has expired, a new [Entity + Map]{.HTML-Keyboard} shall be created. + - If the data has not expired, **only** the retrieved [Entity + Map]{.HTML-Keyboard} shall be used to determine which [Context Source + Registrations]{.HTML-Keyboard} match the Entity ID. + + - If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the + request, and no [Entity Map]{.HTML-Keyboard} currently exists, then a new + [Entity Map]{.HTML-Keyboard} shall be created. + +- For [Context Source Registrations]{.HTML-Keyboard} that match and support the + retrieveEntity operation (see operations and operation groups in clause 9.2), + implementations shall do the following: + - If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an + [Entity Map]{.HTML-Keyboard} entry linked to a [Context Source + Registration]{.HTML-Keyboard} is found, the location of the linked [Entity + Map]{.HTML-Keyboard} shall be passed as part of any forwarded request. + - For any **exclusive**, **redirect** and **inclusive** [Context Source + Registrations]{.HTML-Keyboard}, the request is forwarded for remote + retrieval by matching endpoints, and remote Attribute data for the Entity is + received. If an _`expiresAt`_ _DateTime_ is present on the Entity and the + date lies in the past, the Attribute data shall be discarded, otherwise the + Attribute data is then merged together according to the algorithm defined in + clause 8.5. + - For any **auxiliary** [Context Source Registrations]{.HTML-Keyboard} the + remote Attribute data received is added to the payload only when an + Attribute is not present in any of the Attribute data received elsewhere. + - If an [Entity Map]{.HTML-Keyboard} is in use for this operation, the [Entity + Map]{.HTML-Keyboard}'s linked maps are updated to hold the location of every + [Entity Map]{.HTML-Keyboard} used by the [Context Source + Registrations.]{.HTML-Keyboard} + +- Term to URI expansion of Attribute names shall be observed as mandated by + clause 8.2.4. +- For each Attribute found in the target Entity, when the _`datasetId`_ + parameter is provided in the request: + - Filter the Attribute instances based on the _`datasetId`_ arameter, i.e. + keep only the Attribute instances whose _`datasetId`_ is specified. The + default Attribute instance is matched, if ["@none"]{.HTML-Code} is + specified. + - If there is no Attribute instance whose _`datasetId`_ matches the value of + the parameter, the Attribute shall not be returned with the Entity. + +- If the optional Attribute list is present and the NGSI-LD endpoint does know + about a matching Entity for the Entity ID, but this Entity does not have any + of the Attributes in the Attribute list, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- If the Accept Header is set to ["application/json"]{.HTML-Code} or + ["application/ld+json"]{.HTML-Code}, return a JSON-LD object representing the + Entity as mandated by clause 5.2.6.4.1 and containing only the Attributes + requested (if present). + - If the Prefer Header [n.14] is set to + ["ngsi-ld=<​version>"]{.HTML-Code} then the ContextBroker shall + endeavour to amend the JSON-LD object to conform to the specified version of + the NGSI-LD specification as mandated in clause 9.5.3, and return a + Preference-Applied Header set to + ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. + +- If the Accept Header is set to ["application/geo+json"]{.HTML-Code}, a GeoJSON + _Feature_ object representing the entity as mandated by clause 5.2.6.11.1 and + containing only the Attributes requested (if present): + - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then + the _Feature_ object will also contain an _`@context`_ field. + - If the Prefer Header is set to ["body=json"]{.HTML-Code} the _`@context`_ is + set as a Link Header and removed from the Feature object. + +#### 10.4.2.5 Output data + +A JSON-LD object representing the target Entity as mandated by clause 5.2.6.4.1 +or a GeoJSON _Feature_ as mandated by clause 5.2.6.11.1. + +If a restrictive list of Entity member names is present, the Entity is reduced +down to only contain the defined Entity members (applies to all Entities in the +payload in the case of [Linked Entity]{.HTML-Keyboard} retrieval). + +If an exclusionary list of Entity member names is present, the defined Entity +members listed are removed from the Entity (applies to all Entities in the +payload in the case of [Linked Entity]{.HTML-Keyboard} retrieval). + +If any of the returned Attributes corresponds to a +[VocabProperty]{.HTML-Keyboard}, the returned value shall be compacted according +to the supplied _`@context`_. + +If a language filter is specified and any of the returned Attributes corresponds +to a _LanguageProperty_, the _LanguageProperty_ in question shall be converted +into a _Property_. The value of this _Property_ shall correspond to the value of +the string or strings from the matching key-value pair of the _`languageMap`_ +where the key matches the language filter. A non-reified subproperty _`lang`_ +shall be included in the response indicating the chosen language. + +If no match can be made for a _LanguageProperty_ then a single language shall be +chosen, up to the implementation. + +If **inline** [Linked Entity]{.HTML-Keyboard} **retrieval** (see clause 7.7.2) +is specified, and any of the returned Attributes corresponds to an annotated +_Relationship_, then unless a URI has been previously encountered, an _`entity`_ +sub-Property shall be included in the response holding the [Linked +Entity]{.HTML-Keyboard} data for each URI corresponding to that _Relationship's_ +target _`object`_ URI. If any of the returned Attributes corresponds to an +annotated _ListRelationship_, then an _`entityList`_ subproperty shall be +included in the response holding the **ordered** array of [Linked +Entities]{.HTML-Keyboard} corresponding to that _ListRelationship's_ target +_`objectList`_ URIs unless a URI has been previously encountered. + +If **flattened** [Linked Entity]{.HTML-Keyboard} **retrieval** (see clause +7.7.3) is specified, the response shall be an array of JSON-LD objects +representing the target entity itself and the targets of its _Relationships_. If +any of the returned Attributes corresponds to an annotated _Relationship_, +unless a target URI has been previously encountered, thedata corresponding to +each URI of the Relationship's target _`object`_ URIs is appended to the array. +If any of the returned Attributes corresponds to an annotated +_ListRelationship_, then an **ordered** array of additional [Linked +Entities]{.HTML-Keyboard} is appended to the array which hold the data +corresponding to each of the URIs found within _ListRelationship's_ target +_`objectList`_ unless a URI has been previously encountered. + +Flattened [Linked Entity]{.HTML-Keyboard} retrieval output changes to a GeoJSON +_FeatureCollection_ as mandated by clause 5.2.6.11.2 if the Accept Header is set +to ["application/geo+json"]{.HTML-Code}. + +If the location of a previously generated [Entity Map]{.HTML-Keyboard} was +passed into the request, or a flag to return an [Entity Map]{.HTML-Keyboard} was +present in the request, the location of the [Entity Map]{.HTML-Keyboard} used in +the operation shall be returned in a specific field in the response. + +### 10.4.3 Query Entities + +#### 10.4.3.1 Description + +This operation allows querying an NGSI-LD system. + +#### 10.4.3.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve a set of entities which +matches a specific query from an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Query Entities use case +::: + + + +#### 10.4.3.3 Input data + +- A reference to a JSON-LD _`@context`_ (optional). +- A selector of Entity types as specified by clause 7.2.2 (optional). Both type + names (short hand string) and fully qualified type names (URI) are allowed in + the selector. +- A list (one or more) of Entity identifiers (optional). +- An id pattern as a regular expression (optional). +- An NGSI-LD query (to filter out Entities by Attribute values) as per clause + 7.2.3 (optional). +- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as + mandated by clause 7.2.4 (optional). +- A NGSI-LD Scope query (to filter out Entities based on their Scope) as + mandated by clause 7.2.5 (optional). +- A restrictive list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + retrieved (projection attributes as defined by clause 7.3.2) (optional). +- An exclusionary list member names (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, + ["scope"]{.HTML-Code} or an Attribute name) to be removed (projection + attributes as defined by clause 7.3.2) (optional). +- A list (one or more) of Attribute names of which at least one shall exist in + order for an Entity to be selected, and also used as query projection + attributes (optional, deprecated). +- An NGSI-LD query (called context source filter, to filter out [Context + Sources]{.HTML-Keyboard} by the values of properties that describe them) as + per clause 7.2.3 (optional). +- A limit to the number of Entities to be retrieved. See clause 7.4.2. +- A specified language filter as per clause 7.2.7 (optional). +- A list (one or more) of Attribute names whose values shall be expanded to URIs + prior to executing a query (optional). +- An optional flag indicating whether to include additional [Linked + Entities]{.HTML-Keyboard} corresponding to the _Relationships_ retrieved and + how to format those [Linked Entities]{.HTML-Keyboard}. See clause 7.7 + (optional). +- A limit to the depth of [Linked Entities]{.HTML-Keyboard} to search whilst + traversing an Entity Graph. See clause 7.7 (optional). +- A list (one or more) of [Linked Entity]{.HTML-Keyboard} identifiers previously + encountered whilst traversing an Entity Graph. See clause 7.7 (optional). +- A flag indicating whether to return the location of the [Entity + Map]{.HTML-Keyboard} used within the operation (optional). +- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity + Map]{.HTML-Keyboard} is to be created (optional). +- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching + Entity registrations (optional). +- A _`datasetId`_ parameter that specifies which Attribute instances are to be + selected as defined by clause 8.5 (optional). +- A list of Entity member names (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, + ["scope"]{.HTML-Code} or an Attribute name) to be used to define the preferred + ordering of Entities retrieved (Entity ordering attributes as defined by + clause 7.6.2) (optional). +- A preferred collation setting to be used when applying ordering of Entities + (optional). +- A location to be used when applying ordering of Entities (optional). +- A defined geometry type to be used when applying ordering of Entities + (optional). +- A flag indicating whether split Entities are to be expected, i.e. Entities + whose information is distributed across different [Context + Sources]{.HTML-Keyboard} (optional). +- In the case of GeoJSON representation, the name of the _GeoProperty_ attribute + to use as the geometry for the GeoJSON representation as mandated by clause + 5.3.3 (optional). + +In the general case, it is not possible to retrieve a set of entities by only +specifying desired Entity identifiers, without further specifying restrictions +on the entities' types or attributes, either explicitly, via selector of Entity +types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. +If the execution of the operation is limited to the local scope (see clause +8.6), no further restrictions have to be provided. + +#### 10.4.3.4 Behaviour + +- At least one of the following input data shall be provided: + + + + a. selector of Entity Types; + b. list of Attribute names, including at least one non-system Attribute; + c. NGSI-LD Query, including at least one non-system Attribute; + d. NGSI-LD GeoQuery; + e. local scope (see clause 8.6). + + + +- If none of the above is provided, then an error of type + [BadRequestData]{.HTML-Error} + +- If the list of Entity identifiers includes a URI which it is not valid, or the + query, geoquery or context source filter are not syntactically valid (as per + the referred clauses 7.2.3 and 7.2.4) an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If projection attributes are present and indicate the use of [Linked + Entity]{.HTML-Keyboard} retrieval, and the use of [Linked + Entity]{.HTML-Keyboard} retrieval is not specified, or the projected attribute + depth exceeds the [Linked Entity]{.HTML-Keyboard} retrieval depth, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the filter conditions specified by the query includes [Linked + Entity]{.HTML-Keyboard} attributes, and the use of [Linked Entity + ]{.HTML-Keyboard} retrieval is not specified, or the [Linked Entity + ]{.HTML-Keyboard} attribute query depth exceeds the [Linked Entity + ]{.HTML-Keyboard} retrieval depth, an error of type + [BadRequestData]{.HTML-Error} shall be raised (too deep query). +- If geometryProperty parameter is present and the Accept Header is not set to + ["application/geo+json",]{.HTML-Code} then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the ordering parameter is present and the execution of the operation is not + limited to the local scope (see clause 8.6) then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the ordering parameter is present and refers to ordering by distance and no + location is present, then an error of type [BadRequestData]{.HTML-Error} shall + be raised. +- If a preferred collation setting is present and it does not conform to a valid + ICU collation (see IETF RFC 6067 [n.15]) then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If a location to be used when applying ordering of Entities setting is present + and it is not syntactically valid (as per the referred clauses 7.2.3 and + 7.2.4) or an error of type [BadRequestData]{.HTML-Error} shall be raised. +- Otherwise, + +- Term to URI expansion of type and Attribute names shall be performed, as + mandated by clause 8.2.4. +- If a list of Attribute names whose values shall be expanded to URIs has been + supplied, JSON-LD type coercion shall be performed as mandated by clause + 8.2.4. + +- If split entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split entities, and local scope + is not specified, implementations shall run a query that shall return an + Entity Array containing all the Entities found locally, that meet all of the + following conditions (given the respective parameter is provided): + - id is equal to any of the id(s) passed as a parameter; + - the Entity Type names match the selector of Entity Types (expanded) that is + passed as a parameter; + - id matches the id pattern passed as a parameter. + +- Otherwise, implementations shall run a query that shall return an Entity Array + containing all the Entities found locally, that meet **all** of the following + conditions (given the respective parameter is provided): + - id is equal to any of the id(s) passed as a parameter; + - the Entity Type names match the selector of Entity Types (expanded) that is + passed as a parameter; + - Attribute matches any of the expanded attribute(s) in the list that is + passed as a parameter; + - id matches the id pattern passed as a parameter; + - the filter conditions specified by the query are met (as mandated by clause + 7.2.3); + - the geospatial restrictions imposed by the geoquery are met (as mandated by + clause 7.2.40); if there are multiple instances of the GeoProperty on which + the geoquery is based, it is sufficient if any of these instances meets the + geospatial restrictions; + - if the Scope query is present, it shall match a present Entity Scope (as + mandated by clause 7.2.5, for an example see annex C, clause C.5.15); + - if the Attribute list is present, in order for an Entity to match, it shall + contain at least one of the Attributes in the projection Attribute list. + +- If the ContextBroker implementation supports the use of [Entity + Maps]{.HTML-Keyboard} then: + - If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of + matching Entity registrations is present it shall be retrieved: + - If the resource cannot be found, or the data has expired, a new [Entity + Map]{.HTML-Keyboard} shall be created. + - If the data has not expired, **only** the retrieved [Entity + Map]{.HTML-Keyboard} shall be used to determine which [Context Source + Registrations]{.HTML-Keyboard} match the Entity ID. + + - If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the + request, and no [Entity Map]{.HTML-Keyboard} currently exists, then a new + [Entity Map]{.HTML-Keyboard} shall be created. + +- Unless local scope is specified (see clause 8.6), for [Context Source + Registrations]{.HTML-Keyboard} that match the query and support the + "queryEntity" operation (see operations and operation groups in clause 9.2), + implementations shall do the following: + - If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an + [Entity Map]{.HTML-Keyboard} entry linked to a [Context Source + Registration]{.HTML-Keyboard} is found, the location of the [Entity + Map]{.HTML-Keyboard} shall be passed as part of the forwarded request. + - If split entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split entities, the filters + (filter conditions specified by the query, geospatial restrictions imposed + by the geoquery, Scope query, Attributes) shall be removed before forwarding + the request. These filters then have to be applied after the Entity + information from different [Context Sources]{.HTML-Keyboard} and local + information, if there is any, has been aggregated. + - For any **exclusive**, **redirect** and **inclusive** [Context Source + Registrations]{.HTML-Keyboard}, the request is forwarded for remote querying + by matching endpoints. The result of each remote query is an Entity Array. + Within each Entity Array, any Entities where an _`expiresAt`_ _DateTime_ is + present and the date lies in the past shall be discarded. The Entity Arrays + are then merged together with the locally queried result according to the + algorithm defined in clause 7.2.3. + - For any **auxiliary** [Context Source Registrations]{.HTML-Keyboard}, the + request is forwarded for remote querying by matching endpoints. Data from + the Entity Array received is added to the payload only when an Attribute is + not already present in the merged Entity Arrays are received elsewhere. + +- If split Entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split Entities, and local scope + is not specified, the following filters shall be applied on the aggregated + Entities: + - the filter conditions specified by the query are met (as mandated by clause + 7.2.3); + - the geospatial restrictions imposed by the geoquery are met (as mandated by + clause 7.2.4); if there are multiple instances of the GeoProperty on which + the geoquery is based, it is sufficient if any of these instances meets the + geospatial restrictions; + - if the Scope query is present, it shall match a present Entity Scope (as + mandated by clause 7.2.5, for an example see annex C, clause C.5.15); + - if the Attribute list is present, in order for an Entity to match, it shall + contain at least one of the Attributes in the projection Attribute list. + +- Pagination logic shall be in place as mandated by clause 7.4.2. + +- If in the process of obtaining the query result it is necessary to issue a + [Context Source]{.HTML-Keyboard} discovery operation, the same [Context + Source]{.HTML-Keyboard} filter input parameter (if present) shall be + propagated. + +- For each Attribute found in the target Entity, when _`datasetId`_ parameter is + provided in the request: + - Filter the Attribute instances based on the _`datasetId`_ parameter, i.e. + keep only the Attribute instances whose _`datasetId`_ is specified. The + default Attribute instance is matched, if ["@none"]{.HTML-Code} is + specified. + - If there is no Attribute instance whose _`datasetId`_ matches the value of + the parameter, the Attribute shall not be returned with the Entity. + +- If the Accept Header is set to ["application/json"]{.HTML-Code} or + ["application/ld+json",]{.HTML-Code} a JSON-LD array is returned, representing + the Entities as mandated by clause 5.2.6.4.1 and containing only the + Attributes requested (if present). + - If the Prefer Header [n.14] is set to + ["ngsi-ld=<​version>"]{.HTML-Code} then the ContextBroker shall + endeavour to amend the elements of the JSON-LD array to conform to the + specified version of the NGSI-LD specification as mandated in clause 9.5.3, + and return a Preference-Applied Header set to + ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. + +- If the Accept Header is set to ["application/geo+json",]{.HTML-Code} the + response shall be a GeoJSON _FeatureCollection_ as mandated by clause + 5.2.6.11.2, with each _Feature_ within the _FeatureCollection_ containing only + the Attributes requested (if present): + - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then + the _FeatureCollection_ will also contain an _`@context`_ field. + - If the Prefer Header is set to ["body=json]{.HTML-Code}" the _`@context`_ is + sent as a Link Header and removed from the _FeatureCollection_ object. + +#### 10.4.3.5 Output data + +A JSON-LD array representing the matching entities as defined by clause +5.2.6.4.1 or in the case of GeoJSON requests a _FeatureCollection_ as mandated +by clause 5.2.6.11.2. If Entity ordering is specified (see clause 7.6.2), then +the JSON-LD array or _FeatureCollection_ returned shall be ordered according to +the list of member names specified. For each matching Entity, only the +Attributes specified by the Attribute list parameter shall be included. If such +parameter is not present, then all Attributes shall be included. + +If a restrictive list of Entity member names is present, every Entity within the +payload body is reduced down to only contain the defined Entity members. + +If an exclusionary list of Entity member names is present, the defined Entity +members listed are removed from each Entity within the payload. + +If any of the returned Attributes corresponds to a +[VocabProperty]{.HTML-Keyboard}, the returned value shall be compacted according +to the supplied _`@context`_. + +If a language filter is specified and any of the returned Attributes corresponds +to a _LanguageProperty_, the _LanguageProperty_ in question shall be converted +into a _Property_. The value of this _Property_ shall correspond to the value of +the string or strings from matching key-value pair of the _`languageMap`_ where +the key matches the language filter. A non-reified subproperty _`lang`_ shall be +included in the response indicating the chosen language. + +If no match can be made for a _LanguageProperty_, then the default identified by +the JSON-LD ["@none"]{.HTML-Code} shall be chosen if present, otherwise the +choice of a single language is up to the implementation. + +If **inline** [Linked Entity]{.HTML-Keyboard} **retrieval** (see clause 7.7.2) +is specified, and any of the returned Attributes corresponds to an annotated +_Relationship_, then unless a URI has been previously encountered, an _`entity`_ +subproperty shall also be included in the response holding the data for each URI +corresponding to that _Relationship's_ target _`object`_ URIs. If any of the +returned Attributes corresponds to an annotated _ListRelationship_, then an +_`entityList`_ subproperty shall also be included in the response holding the +**ordered** data corresponding to that _ListRelationship's_ target +_`objectList`_ URIs, unless a URI has been previously encountered. + +If **flattened** [Linked Entity]{.HTML-Keyboard} **retrieval** (see clause +7.7.3) is specified, the response shall be an array of JSON-LD objects +representing the matching entities and the targets of their _Relationships_. If +any of the returned Attributes corresponds to an annotated _Relationship_, +unless a URI has been previously encountered, then data for each URI +corresponding to the _Relationship's_ target _`object`_ URIs is appended to the +array. If any of the returned Attributes corresponds to an annotated +_ListRelationship_, then an array of additional [Linked +Entities]{.HTML-Keyboard} is appended to the array which hold the data +corresponding to each of the URIs found within _ListRelationship's_ target +_`objectList`_ unless a URI has been previously encountered. + +If the location of a previously generated [Entity Map]{.HTML-Keyboard} was +passed into the request, or a flag to return an [Entity Map]{.HTML-Keyboard} was +present in the request, the location of the [Entity Map]{.HTML-Keyboard} used in +the operation shall be returned in a specific field in the response. + +### 10.4.4 Retrieve Attribute Value + +#### 10.4.4.1 Description + +#### 10.4.4.2 Use case diagram + +#### 10.4.4.3 Input data + +#### 10.4.4.4 Behaviour + +#### 10.4.4.5 Output data + +## 10.5 Context Information Subscription + +### 10.5.1 Introduction + +Clause 10.5 defines the operations related to context information subscriptions +in an NGSI-LD system. A Context Information Subscription allows a [Context +Subscriber]{.HTML-Definition} to receive notifications about changes in context +information based on specified criteria. + +### 10.5.2 Create Subscription + +#### 10.5.2.1 Description + +This operation allows creating a new subscription. + +#### 10.5.2.2 Use case diagram + +A [Context Subscriber]{.HTML-Definition} can create a subscription to receive +context updates within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Create subscription use case +::: + + + +#### 10.5.2.3 Input data + +- A data structure (represented in JSON-LD) conforming to the Subscription data + type as mandated by clause 5.2.6.5.2. + +#### 10.5.2.4 Behaviour + +- If the data types, cardinalities and restrictions expressed by clause + 5.2.6.5.2 are not met, then an error of type [BadRequestData]{.HTML-Error} + shall be raised. +- If the NGSI-LD endpoint already knows about this Subscription, as there is an + existing Subscription whose id (URI) is equivalent, an error of type + [AlreadyExists]{.HTML-Error} shall be raised. +- If the subscription document does not include a Subscription identifier, a new + locally unique identifier (URI) shall be automatically generated by the + implementation. +- Then, implementations shall add a new Subscription. The behaviour for + corresponding notifications shall be as per clause 10.5.7. The parameters of + the created Subscription shall be configured as follows: + - The Subscription expiration date shall be equal to the value of the + [expiresAt]{.HTML-Variable} member. If the expiration timestamp provided + represents a moment before the current date and time, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. If there is no + [expiresAt]{.HTML-Variable} member the Subscription shall be considered as + perpetual. + - If the value of the _`isActive`_ field is not included or is _`true`_ then + the initial status of the Subscription shall be set to + ["active"]{.HTML-Code}. + - If the value of the _`isActive`_ field is _`false`_, then the initial status + of the Subscription shall be set to ["paused"]{.HTML-Code}. + - If present, the subscribed entities shall be those matching the conditions + expressed under the [EntitySelector]{.HTML-Definition}, as defined in clause + 5.2.6.5.1. + - Watched Attributes shall be those Attributes (subject to clause 8.2.4 Term + to URI expansion) pertaining to the subscribed entities (if present) and + conveyed through the [watchedAttributes]{.HTML-Variable} member. Watched + Attributes are those that trigger a new notification when they are changed. + A non-present [watchedAttributes]{.HTML-Variable} member means that all + Attributes shall be watched. If no subscribed entities have been specified, + all entities with attributes matching at least one member of + [watchedAttributes]{.HTML-Variable} are subscribed to. + - The _`@context`_ to be used for sending Notifications related to this + Subscription shall be the one specified in the _`jsonldContext`_ field. If + not present, the _`jsonldContext`_ field shall be initialized with the + _`@context`_ applicable for the Subscription (if _`@context`_ is also not + present in the Subscription, see clause 8.2.2). When the remote JSON-LD + _`@context`_ referenced by the _`jsonldContext`_ field is not available + implementations shall raise an error of type + [LdContextNotAvailable]{.HTML-Error}. If the remote JSON-LD _`@context`_ + referenced by the _`jsonldContext`_ field is invalid, implementations shall + raise an error of type [BadRequestData]{.HTML-Error}. + - Based on the content of the Subscription, a [Context Source + Registration]{.HTML-Keyboard} Subscription shall be created (clause 12.4.2). + The mapping of the [id]{.HTML-Variable} of the Subscription to the returned + [subscriptionId]{.HTML-Variable} of the [Context Source + Registration]{.HTML-Keyboard} Subscription shall be stored to enable + updating or deleting the [Context Source Registration]{.HTML-Keyboard} + Subscription in case of changes to the Subscription. + +- If the subscription defines a [timeInterval]{.HTML-Variable} member, a + Notification shall be sent periodically, when the time interval (in seconds) + specified in such value field is reached, regardless of Attribute changes. +- If [timeInterval]{.HTML-Variable} is not defined, whenever there is a change + in the watched Attribute nodes (Properties or Relationships) of the concerned + Entities, implementations shall post a new Notification as per the rules + defined by clause 10.5.7. +- If [localOnly=false,]{.HTML-Variable} each time a [Context + Source]{.HTML-Keyboard} Notification with the [subscriptionId]{.HTML-Variable} + of the previously created [Context Source Registration]{.HTML-Keyboard} + Subscription is received, implementations shall do the following: + - For any **exclusive**, **redirect** and **inclusive** [Context Source + Registration]{.HTML-Keyboard} received as part of the notification, + implementation shall do the following depending on the + [triggerReason]{.HTML-Variable}: + - If the [triggerReason]{.HTML-Variable} is ["newlyMatching"]{.HTML-Code} + and the [Context Source Registration]{.HTML-Keyboard} indicates support + for the Create Subscription operation, a copy of the original Subscription + shall be reduced to what is matched by the registration information. If + the [splitEntities]{.HTML-Variable} member is explicitly set to true or, + if not explicitly set, the default setting of the deployment allows split + entities, the members [q]{.HTML-Variable}, [geoQ]{.HTML-Variable} and + [scopeQ]{.HTML-Variable} shall be removed from the created copy of the + original Subscription. Also from the [notification]{.HTML-Variable} + member, the [attributes]{.HTML-Variable}, [pick]{.HTML-Variable} and + [omit]{.HTML-Variable} members are to be removed. The copied Subscription + is then forwarded to the [Context Source]{.HTML-Keyboard} as a new + Subscription where the notification endpoint is set to that of the local + Broker. The mapping of the received [subscriptionId]{.HTML-Variable} with + the own Subscription identifier is stored to enable forwarding received + notifications to the original subscriber. In addition, a mapping of the id + of the [Context Source Registration]{.HTML-Keyboard} to the received + [subscriptionId]{.HTML-Variable} is stored, to enable updating or deleting + the subscription in case of changes. + - If the [triggerReason]{.HTML-Variable} is ["updated"]{.HTML-Code} and the + [Context Source Registration]{.HTML-Keyboard} indicates support for the + Update Subscription operation, an update of the original Subscription, + reduced to what is matched by the registration information, shall be + created. If the [splitEntities]{.HTML-Variable} member is explicitly set + to true or, if not explicitly set, the default setting of the deployment + allows split entities, the members [q]{.HTML-Variable}, + [geoQ]{.HTML-Variable} and [scopeQ]{.HTML-Variable} shall be removed from + the updated Subscription. Also from the [notification]{.HTML-Variable} + member the [attributes]{.HTML-Variable}, [pick]{.HTML-Variable} and + [omit]{.HTML-Variable} members are to be removed. The updated Subscription + is then forwarded to the [Context Source]{.HTML-Keyboard} with the + subscriptionId related to the [Context Source + Registration]{.HTML-Keyboard}. As an optimization, an implementation may + keep the originally forwarded [Context Source + Registration]{.HTML-Keyboard} and compare with the new one to only forward + the update, if there was a relevant change. + - If the [triggerReason]{.HTML-Variable} is ["noLongerMatching"]{.HTML-Code} + and the [Context Source Registration]{.HTML-Keyboard} indicates support + for the delete Subscription operation, a delete Subscription shall be + forwarded to the [Context Source]{.HTML-Keyboard} with the + [subscriptionId]{.HTML-Variable} related to the [Context Source + Registration]{.HTML-Keyboard}. + +- Implementations shall ensure that, when the Subscription expiration date is + due, the status of the Subscription changes automatically to + "[expired"]{.HTML-Code}, so that notifications will no longer be sent. + +#### 10.5.2.5 Output data + +A URI identifying the newly created Subscription. + +### 10.5.3 Update Subscription + +#### 10.5.3.1 Description + +This operation allows updating an existing subscription. + +#### 10.5.3.2 Use case diagram + +A [Context Subscriber]{.HTML-Definition} can update an existing subscription +within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Update subscription use case +::: + + + +#### 10.5.3.3 Input data + +- Subscription identifier (URI), the target subscription. +- A JSON-LD document representing a Subscription Fragment. + +#### 10.5.3.4 Behaviour + +- If the Subscription id is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD System does not know about the target Subscription, because + there is no existing Subscription whose id (URI) is equivalent, an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. +- If the data types and restrictions expressed by clause 5.2.6.5.2 are not met + by the _Subscription Fragment_, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- Term to URI expansion of Attribute names shall be observed as mandated by + clause 8.2.4. +- If the _`jsonldContext`_ field is present and the referenced JSON-LD + _`@context`_ is not available, implementations shall raise an error of type + [LdContextNotAvailable]{.HTML-Error}. If the referenced JSON-LD _`@context`_ + is invalid, implementations shall raise an error of type + [BadRequestData]{.HTML-Error}. +- Then, implementations shall modify the target Subscription as mandated by + clause 8.4.2. +- Finally, the following extra behaviour shall be observed when updating + Subscriptions: + - If _`isActive`_ is equal to _`true`_ and [expiresAt]{.HTML-Variable} is not + present, then [status]{.HTML-Variable} shall be updated to + ["active",]{.HTML-Code} if and only if, the previous value of + [status]{.HTML-Variable} was different than ["expired"]{.HTML-Code}. + - If _`isActive`_ is equal to _`true`_ and [expiresAt]{.HTML-Variable} + corresponds to a [DateTime]{.HTML-Definition} in the future, then + [status]{.HTML-Variable} shall be updated to ["active"]{.HTML-Code}. + - If _`isActive`_ is equal to _`false`_ and [expiresAt]{.HTML-Variable} is not + present, then [status]{.HTML-Variable} shall be updated to + ["paused]{.HTML-Code}", if and only if, the previous value of + [status]{.HTML-Variable} was different than ["expired"]{.HTML-Code}. + - If only [expiresAt]{.HTML-Variable} is included and refers to a + [DateTime]{.HTML-Definition} in the future, then [status]{.HTML-Variable} + shall be updated to ["active",]{.HTML-Code} if and only if the previous + value of [status]{.HTML-Variable} was ["expired"]{.HTML-Code}. + - If [expiresAt]{.HTML-Variable} is included but referring to a + [DateTime]{.HTML-Definition} in the past, then a + [BadRequestData]{.HTML-Error} error shall be raised, regardless the value of + _`isActive`_. + - Based on the mapping of the Subscription to its respective [Context Source + Registration]{.HTML-Keyboard} Subscription (see clause 5.8.1.4), that + [Context Source Registration]{.HTML-Keyboard} Subscription shall be updated + (clause 12.4.3). + +#### 10.5.3.5 Output data + +None. + +### 10.5.4 Retrieve Subscription + +#### 10.5.4.1 Description + +This operation allows retrieving an existing subscription. + +#### 10.5.4.2 Use case diagram + +A [Context Subscriber]{.HTML-Definition} can retrieve a specific subscription +from an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve subscription use case +::: + + + +#### 10.5.4.3 Input data + +Id (URI) of the subscription to be retrieved (target subscription). + +#### 10.5.4.4 Behaviour + +- If the subscription Id is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the identifier provided does not correspond to any existing subscription in + the system then an error of type [ResourceNotFound]{.HTML-Error} shall be + raised. +- Otherwise, implementations shall query the subscriptions and obtain the + subscription data to be returned to the caller. + +#### 10.5.4.5 Output data + +A JSON-LD object representing the subscription details as mandated by clause +5.2.6.5.2. + +### 10.5.5 Query Subscriptions + +#### 10.5.5.1 Description + +This operation allows querying existing Subscriptions. + +#### 10.5.5.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can query the existent Subscriptions from +an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Query subscriptions use case +::: + + + +#### 10.5.5.3 Input data + +A limit to the number of subscriptions to be retrieved. See clause 7.4.2. + +#### 10.5.5.4 Behaviour + +- The NGSI-LD system shall list all the existing subscriptions up to the limit + specified as input data. If no limit is specified the number of subscriptions + retrieved may depend on the implementation. +- Pagination logic shall be in place as mandated by clause 7.4.2. + +#### 10.5.5.5 Output data + +A list (represented as a JSON array) of JSON-LD objects each one representing +subscription details as mandated by clause 5.2.6.5.2. + +### 10.5.6 Delete Subscription + +#### 10.5.6.1 Description + +This operation allows deleting an existing subscription. + +#### 10.5.6.2 Use case diagram + +A [Context Subscriber]{.HTML-Definition} can delete a subscription within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete subscription use case +::: + + + +#### 10.5.6.3 Input data + +A subscription identifier (URI). + +#### 10.5.6.4 Behaviour + +- If the subscription Id is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the subscription id provided does not correspond to any existing + subscription in the system, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- Otherwise, implementations shall delete the Subscription and no longer perform + notifications concerning such Subscription. +- Using the mapping of the own Subscription identifier to each of the + subscriptionId of a subscription to a [Context Source]{.HTML-Keyboard}, a + delete Subscription shall be forwarded to each such [Context + Source]{.HTML-Keyboard}, if the delete Subscription operation is supported as + indicated in the corresponding [Context Source Registration]{.HTML-Keyboard}: + - Based on the mapping of the Subscription to its respective [Context Source + Registration]{.HTML-Keyboard} Subscription (see clause 10.5.2.4), that + [Context Source Registration]{.HTML-Keyboard} Subscription shall be deleted + (clause 12.4.6). + +#### 10.5.6.5 Output data + +None. + +### 10.5.7 Notification behaviour + +A notification is a message that allows a subscriber to be aware of the changes +in subscribed Entities. Implementations shall exhibit the following behaviour: + +- Notifications shall only be sent if and only if the status of the + corresponding subscription ([subscription.status]{.HTML-Variable}) is + "[active"]{.HTML-Code}, i.e. not "[paused"]{.HTML-Code} nor + "[expired"]{.HTML-Code}. +- If a Subscription defines a [timeInterval]{.HTML-Variable} member, a + Notification shall be sent periodically, when the time interval (in seconds) + specified in such value field is reached, regardless of Attribute changes. The + notification message shall include all the subscribed Entities that match the + query, geoquery and Scope query conditions. If none of query, geoquery and + Scope query are defined, then all subscribed Entities shall be included. For + each entity in the notification, only the Attribute instances are to be + included that match the _`datasetId`_ member in Subscription. If there are no + matching Entities, no Notification is sent. +- If a Subscription does not define a [timeInterval]{.HTML-Variable} term, the + notification shall be sent whenever there is a change in the watched + Attributes. An Attribute is considered to change when any of the members + (including children) in its corresponding JSON-LD node is updated with a value + different than the existing one. The notification message shall include all + the subscribed Entities that changed and that match (as mandated by clauses + 7.2.3, 7.2.4 and 7.2.5) the query, geoquery and Scope query conditions. If + query, geoquery and scopeQuery are all not defined then all subscribed + Entities that changed shall be included. If, for an Entity, there are multiple + instances of the [GeoProperty]{.HTML-Definition} on which the geoquery is + based, it is sufficient if any of these instances meets the geospatial + restrictions. For each entity in the notification, only the Attribute + instances are to be included that match the _`datasetId`_ member in + Subscription. Finally, if a [Context Source]{.HTML-Keyboard} filter is + defined, then only the subscribed Entities whose origin [Context + Source]{.HTML-Keyboard} matches the referred filter shall be included. +- If a Notification with a [subscriptionId]{.HTML-Variable} is received that has + a mapping to a local Subscription identifier, the Notification shall be + copied. If the [splitEntities]{.HTML-Variable} member of the local + Subscription is explicitly set to true or, if not explicitly set, the default + setting of the deployment allows split entities: + - The Entities contained in the data member of the Notification shall be + retrieved locally and from all Context Sources that have information about + these Entities, except for the one from which the Notification has been + received. + - The retrieved Entities then shall be merged with the Entities in the data + member. + - All Entities that do not match the query, geoquery and Scope query + conditions of the local Subscription shall be removed from the data member. + +- If there are Entities in the _`data`_ member of the Notification copy, the + Notification copy shall be forwarded to the Notification endpoint specified in + the local Subscription, using this local Subscription identifier instead of + the _`subscriptionId`_ **received**. +- A Notification shall be sent as follows: + - The structure of the notification message shall be as mandated by clause + 5.2.6.9.1. + - The _`@context`_ to be used is the one specified in the _`jsonldContext`_ + field of the corresponding Subscription. + - The Attributes included (Properties or Relationships) shall be those + specified by the _`notification.attributes`_ member in the Subscription data + type (clause 5.2.6.5.2). Term to URI expansion shall be observed (clause + 8.2.4). The absence of the _`notification.attributes`_ member of a + Subscription means that all Attributes shall be included. If the + notification was triggered by the deletion of an Entity and the + _`notification.showChanges`_ member is not set to _`true`_, only the + _`deletedAt`_ system property shall be provided. In case + _`notification.sysAttrs`_ is set to _`true`_, also _`createdAt`_ and + _`modifiedAt`_ shall be provided. + - If an Attribute has been deleted, only the name of the attribute as key and + the URI ["urn:ngsi-ld:null"]{.HTML-Code} as value shall be provided, unless + more information is required. The latter is the case, if: + - a _`datasetId`_ needs to be provided; + - the _`notification.sysAttrs`_ is set to _`true`_ and thus the system + generated sub-attributes (see clause 5.2.4) have to be provided; + - _`notification.showChanges`_ is set to _`true`_ and thus a previous value + or object has to be provided. + + - In all such cases, a JSON object with all the required information is + provided, where the _`value`_ or the _`object`_ is set to the URI + ["urn:ngsi-ld:null"]{.HTML-Code} respectively or, in case of a + _LanguageProperty_, the _`languageMap`_ is set to + [{"@none":"urn:ngsi-ld:null"}]{.HTML-Code} + +- If the _`notification.format`_ member value is set, the representation of the + entities changes: + +- If the _`notification.format`_ is set to ["concise"]{.HTML-Code} then a + concise representation of the entities shall be provided as defined by clause + 5.3.2.2. +- If the _`notification.format`_ is set to ["simplified"]{.HTML-Code} (or + ["keyValues"]{.HTML-Code} as a synonym), then a simplified representation of + the entities (as mandated by clause 5.3.2.4) shall be provided. +- Otherwise the normalized format as defined by clause 5.3.2.2 shall be used. + +- If the _`notification.pick`_ member value is set, every Entity within the + payload body is reduced down to only contain the defined entity members + listed. +- If the _`notification.omit`_ member value is set, the defined entity members + listed are removed from each Entity within the payload. +- If the _`notification.join`_ member value is set then [Linked + Entity]{.HTML-Keyboard} **retrieval** (as mandated by clause 7.7) shall be + provided. +- If the _`ngsildConformance`_ field of the corresponding Subscription is set, + the notification shall undergo a backwards compatibility operation as defined + by clause 9.5.3 and be amended to conform to the supplied version of the + NGSI-LD specification. +- A Notification shall be sent (as mandated by each concrete binding and + including any optional _`endpoint.receiverInfo`_ defined by clause 5.2.6.6.3) + to the endpoint specified by the _`endpoint.uri`_ member of the notification + structure defined by clause 5.2.6.7.3. The Notification content shall be JSON + by default. However, this can be changed to JSON-LD or GeoJSON by means of the + _`endpoint.accept`_ member. +- The _`notification.timesSent`_ member shall be incremented by one. +- The _`notification.lastNotification`_ member shall be updated with a timestamp + representing the current date and time. +- If the response to the notification request is 200 OK then implementations + shall: + - Update _`notification.lastSuccess`_ with a timestamp representing the + current date and time. + - Update _`notification.status`_ to ["ok"]{.HTML-Code}. + +- If the response to the notification request is different than 200 OKthen + implementations shall: + - Update _`notification.lastFailure`_ with a timestamp representing the + current date and time. + - Update _`notification. Status`_ to ["failed"]{.HTML-Code}. + +## 10.6 Context information availability + +### 10.6.1 Introduction + +Clause 10.6 defines the operations related to retrieving information about the +availability of context information in an NGSI-LD system. This includes +operations to retrieve available entity types and attributes. + +### 10.6.2 Architecture-related aspects of retrieval of Entity Types and Attributes + +Retrieving information about available types or attributes can be an expensive +operation depending on the scale and architectural design decisions of the +NGSI-LD system. This is in particular the case for retrieving the information +about all available entity types and attributes related to all entity +information available in an NGSI-LD system. Especially in the case of +distributed and federated architectures (clause 4.3.4) checking all entities can +be so expensive that it can become practically infeasible. + +Therefore, implementations may only take into account only information that is +available or can be derived from a local datastore and the [Context +Registry]{.HTML-Keyboard}, when implementing the retrieval of available entity +types and attributes, as described in clauses 10.6.3, 10.6.4, 10.6.5, 10.6.6, +10.6.6 and 10.6.8. Context registrations do not always reflect which entity +instances are actually available from a [Context Source]{.HTML-Keyboard} at a +particular point in time, but only which entity instances are possibly available +from a [Context Source]{.HTML-Keyboard}, thus in this case the information about +available entity types and attributes is to be interpreted as "possibly +available". Also, context registrations can have different granularities, i.e. +they possibly only contain entity type or attribute information, and thus the +provided information about available entity types and attributes is possibly +incomplete as a result. In particular the _`attributeNames`_ in the _EntityType_ +data structure (clause 5.2.6.10.3), the _`attributeDetails`_ in the +_EntityTypeInfo_ data structure (clause 5.2.6.10.4), and the _`attributeTypes`_ +and _`typeNames`_ in the _Attribute_ data structure (clause 5.2.6.10.2) may be +provided as empty arrays if the information is not included in the respective +context registration. Implementations may also provide estimates for the entity +count or attribute count instead of the accurate count. + +As an alternative to relying on local information only, the request can be +forwarded to all [Context Sources]{.HTML-Keyboard} which support the respective +operation according to the [Context Source Registration]{.HTML-Keyboard} +describing them. In this case the returned lists are merged with the local list +of entity types before returning them. This approach is more expensive but leads +to a more accurate result. + +### 10.6.3 Retrieve available Entity Types + +#### 10.6.3.1 Description + +This operation allows retrieving a list of NGSI-LD entity types for which entity +instances exist within the NGSI-LD system. + +#### 10.6.3.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve a list of NGSI-LD entity types +from the system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Entity Types use case* +::: + + + +#### 10.6.3.3 Input data + +- An optional JSON-LD context. + +#### 10.6.3.4 Behaviour + +- Return a JSON-LD object representing the list of entity types, as mandated by + clause 5.2.6.10.5, for which entity instances exist within the NGSI-LD system. + See clause 10.6.2 for architecture-related implementation aspects, in + particular the distributed behaviour. + +#### 10.6.3.5 Output data + +A JSON-LD object representing the list of available entity types, as mandated by +clause 5.2.6.10.5. + +### 10.6.4 Retrieve details of available Entity Types + +#### 10.6.4.1 Description + +This operation allows retrieving a list with a detailed representation of +NGSI-LD entity types for which entity instances exist within the NGSI-LD system. +The detailed representation includes the type name (as short name if available +in the provided _`@context`_) and the attribute names that existing instances of +this entity type have. + +#### 10.6.4.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve a list with a detailed +representation of NGSI-LD entity types from the system as shown in +Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Details of Available Entity Types use case +::: + + + +#### 10.6.4.3 Input data + +- An optional JSON-LD context. + +#### 10.6.4.4 Behaviour + +- Return a list of JSON-LD objects representing the details of available entity + types as mandated by clause 5.2.6.10.3 for which entity instances exist within + the NGSI-LD system. See clause 10.6.2 for architecture-related implementation + aspects, in particular the distributed behaviour. + +#### 10.6.4.5 Output data + +A list of JSON-LD objects representing the details of available entity types as +mandated by clause 5.2.6.10.3. + +### 10.6.5 Retrieve available Entity Type information + +#### 10.6.5.1 Description + +This operation allows retrieving detailed entity type information about a +specified NGSI-LD entity type for which entity instances exist within the +NGSI-LD system. The detailed representation includes the type name (as short +name if available in the provided _`@context`_), the count of available entity +instances and details about attributes that existing instances of this entity +type have, including their name (as short name if available in the provided +_`@context`_) and a list of types the attribute can have (e.g. _Property_, +_Relationship_ or _GeoProperty_). + +#### 10.6.5.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve a detailed representation of a +specified NGSI-LD entity type from the system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Entity Type Information use case +::: + + + +#### 10.6.5.3 Input data + +- Entity type name for which detailed information is to be retrieved. +- An optional JSON-LD context. + +#### 10.6.5.4 Behaviour + +- Return a JSON-LD object representing the details of the specified entity type + as mandated by clause 5.2.6.10.4, for which instances exist within the NGSI-LD + system. See clause 10.6.2 for architecture-related implementation aspects. + +#### 10.6.5.5 Output data + +A JSON-LD object representing the details of the specified entity type as +mandated by clause 5.2.6.10.4. + +### 10.6.6 Retrieve available attributes + +#### 10.6.6.1 Description + +This operation allows retrieving a list of NGSI-LD attributes that belong to +entity instances existing within the NGSI-LD system. + +#### 10.6.6.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve a list of NGSI-LD attributes +from the system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Attributes use cas +::: + + + +#### 10.6.6.3 Input data + +- An optional JSON-LD context. + +#### 10.6.6.4 Behaviour + +- Return a JSON-LD object representing the list of attributes as mandated by + clause 5.2.6.10.2 that belong to entity instances existing within the NGSI-LD + system. See clause 10.6.2 for architecture-related implementation aspects, in + particular the distributed behaviour. + +#### 10.6.6.5 Output data + +A JSON-LD object representing the list of available attributes as mandated by +clause 5.2.6.10.2. + +### 10.6.7 Retrieve details of available Attributes + +#### 10.6.7.1 Description + +This operation allows retrieving a list with a detailed representation of +NGSI-LD attributes that belong to entity instances existing within the NGSI-LD +system. The detailed representation includes the attribute name (as short name +if available in the provided _`@context`_) and the type names for which entity +instances exist that have the respective attribute. + +#### 10.6.7.2 Use case diagram + +A context consumer can retrieve a list with a detailed representation of NGSI-LD +attributes from the system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Details of Available Attributes use case +::: + + + +#### 10.6.7.3 Input data + +An optional JSON-LD context. + +#### 10.6.7.4 Behaviour + +Return a list of JSON-LD objects representing the details of available +attributes as mandated by clause 5.2.6.10.1 (restricted to the elements _`id`_, +_`type`_, _`attributeName`_ and _`typeNames`_) that belong to entity instances +existing within the NGSI-LD system. See clause 10.6.2 for architecture-related +implementation aspects, in particular the distributed behaviour. + +#### 10.6.7.5 Output data + +A list of JSON-LD objects representing the details of available attributes as +mandated by clause 5.2.6.10.1 (restricted to the elements _`id`_, _`type`_, +_`attributeName`_ and _`typeNames`_). + +### 10.6.8 Retrieve available Attribute information + +#### 10.6.8.1 Description + +This operation allows retrieving detailed attribute information about a +specified NGSI-LD attribute that belongs to entity instances existing within the +NGSI-LD system. The detailed representation includes the attribute name (as +short name if available in the provided _`@context`_) and the type names for +which entity instances exist that have the respective attribute, a count of +available attribute instances and a list of types the attribute can have (e.g. +_Property_, _Relationship_ or _GeoProperty_). + +#### 10.6.8.2 Use case diagram + +A context consumer can retrieve a list with a detailed representation of NGSI-LD +attributes from the system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Available Attribute Information use case +::: + + + +#### 10.6.8.3 Input data + +- Name of the attribute for which detailed information is to be retrieved. +- An optional JSON-LD context. + +#### 10.6.8.4 Behaviour + +Return a JSON-LD object representing the details of available attributes as +mandated by clause 5.2.6.10.1 that belong to entity instances existing within +the NGSI-LD system. See clause 10.6.2 for architecture-related implementation +aspects, in particular the distributed behaviour. + +#### 10.6.8.5 Output data + +A JSON-LD object representing the details of available attributes as mandated by +clause 5.2.6.10.1. diff --git a/md/clause-11.md b/md/clause-11.md new file mode 100644 index 0000000000000000000000000000000000000000..fd179151a3bcfb3b0b967147a1e5e6e0915ecedd --- /dev/null +++ b/md/clause-11.md @@ -0,0 +1,943 @@ +# 11 Temporal API operations + +## 11.1 Introduction + +Clause+++root describes all operations related to the temporal API. It allows +providing and consuming the [Temporal Evolution of Entities]{.HTML-Keyboard}. +Implementing the [Temporal API]{.HTML-Keyboard} is optional for NGSI-LD systems. + +## 11.2 Temporal context information provision + +### 11.2.1 Introduction + +Clause+++root.2 describes all operations related to providing the [Temporal +Evolution of Entities]{.HTML-Keyboard}. + +### 11.2.2 Create or update (upsert) Temporal Evolution of an Entity + +#### 11.2.2.1 Description + +This operation allows creating or updating (by adding new Attribute instances) +the [Temporal Evolution of an Entity]{.HTML-Keyboard}. + +#### 11.2.2.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can create the [Temporal Evolution of an +Entity]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. + +Similarly, if the Entity already exists then an Update scenario will be in +place. + + + +::: FL + +::: + +::: TF +Figure: Create or Update (Upsert) Temporal Evolution of an Entity use case +::: + + + +#### 11.2.2.3 Input data + +A JSON-LD document representing the [Temporal Evolution of an +Entity]{.HTML-Keyboard} as mandated by Clause+++clause-5+++root.2.6.4.2. + +#### 11.2.2.4 Behaviour + +Implementations shall exhibit the following behaviour: + +- Execute the behaviour defined in Clause+++clause-8+++root.2.3 on JSON-LD + validation. +- If an **exclusive** [Context Source Registration]{.HTML-Keyboard} already + exists for this Entity id (URI), Attributes from matching input data are + forwarded for remote processing: + - For matching Registrations where the "Create or Update (Upsert) Temporal + Evolution of an Entity" operation is supported, the operation is forwarded + to the registration endpoint. If the endpoint then raises an error, this + shall result in an error in case the complete "Create or Update (Upsert) + Temporal Evolution of an Entity" operation failed or in a partial success if + some parts of it succeeded. + - For matching Registrations where the "Create Entity" operation is not + supported, this shall result in an error of type [Conflict]{.HTML-Error} in + case the complete "Create or Update (Upsert) Temporal Evolution of an + Entity" operation failed or in a partial success if some parts of it + succeeded. + + The matching Attributes are then removed from the Fragment and not processed + further. + +- If any **redirect** [Context Source Registrations]{.HTML-Keyboard} exist that + match against the input data, that input data is forwarded for remote + processing by one or more matching endpoints: + - For matching Registrations where the "Create or Update (Upsert) Temporal + Evolution of an Entity" operation is supported, matching input data is + forwarded. If any such endpoint then raises an error, this shall result in + an error in case the complete "Create or Update (Upsert) Temporal Evolution + of an Entity" operation failed or in a partial success if some parts of it + succeeded. + - For matching **redirect** Registrations where the "Create or Update (Upsert) + Temporal Evolution of an Entity" operation is not supported, this shall + result in an error of type [Conflict]{.HTML-Error} in case the complete + "Create or Update (Upsert) Temporal Evolution of an Entity" operation failed + or in a partial success if some parts of it succeeded. + + The matching Attributes are then removed from the Fragment and not processed + further. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded for + remote processing by matching endpoints. +- If the NGSI-LD endpoint already knows about this [Temporal Evolution of an + Entity]{.HTML-Keyboard}, because there is an existing [Temporal Evolution of + an Entity]{.HTML-Keyboard} whose id (URI) is the same, then all the Attribute + instances included by the Temporal Evolution shall be added to the existing + Entity as mandated by Clause+++root.2.3. If _`type`_ is included in the + EntityTemporal Fragment and it includes Entity Type names that are not yet in + the target [Temporal Evolution of an Entity]{.HTML-Keyboard}, add them to the + list of Entity Type names of the target [Temporal Evolution of an + Entity]{.HTML-Keyboard}. +- Otherwise, implementations shall create the provided [Temporal Evolution of an + Entity]{.HTML-Keyboard}. + +#### 11.2.2.5 Output data + +On creation, a URI identifying the newly created Temporal Evolution of an +Entity. None otherwise. + +### 11.2.3 Add Attributes to Temporal Evolution of an Entity + +#### 11.2.3.1 Description + +This operation allows modifying the [Temporal Evolution of an +Entity]{.HTML-Keyboard} by adding new Attribute instances. + +#### 11.2.3.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can add new Attributes or Attribute +instances to an existing [Temporal Evolution of an Entity]{.HTML-Keyboard} +within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Add Attributes to Temporal Evolution of an Entity use case +::: + + + +#### 11.2.3.3 Input data + +- Entity ID (URI) of the target [Temporal Evolution of an + Entity]{.HTML-Keyboard} to be modified with additional Attributes. +- A JSON-LD document representing an NGSI-LD Fragment of _EntityTemporal_, + including only the new Attribute instance(s), and contained by an Array. + +#### 11.2.3.4 Behaviour + +The following behaviour shall be exhibited by compliant implementations: + +- If the Entity ID is not present or it is not a valid URI then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target [Temporal Evolution of + an Entity]{.HTML-Keyboard}, because there is no existing [Temporal Evolution + of an Entity]{.HTML-Keyboard} whose id (URI) is equivalent to the one passed + as a parameter held locally and no matching registrations apply, an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- The behaviour defined in Clause+++clause-8+++root.2.3 on JSON-LD validation. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the Attributes + from matching input data are forwarded for remote processing. For each + matching registration: + - If the "Add Attributes to Temporal Evolution of an Entity" operation is + supported by the matched registration, matching input data is forwarded to + the Registration endpoint. + - If the "Add Attributes to Temporal Evolution of an Entity" operation is not + supported by the matched registration, this shall result in an error of type + [Conflict]{.HTML-Error} if the complete "Add Attributes to Temporal + Evolution of an Entity"operation failed or in a partial success if some + parts of it succeeded. + + The matching Attributes are then removed from the Fragment and not processed + further. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the remaining input data, that input data is also forwarded for + remote processing to matching endpoints. +- If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} exists locally + and matches against the remaining input data, implementations shall do the + following: + - For each Attribute instance included by the _EntityTemporal_ Fragment at + root level: + - The Attribute (considering term expansion rules as mandated by + Clause+++clause-8+++root.2.4) instance(s) shall be added to the target + [Temporal Evolution of an Entity]{.HTML-Keyboard}. +- If _`type`_ is included in the EntityTemporal Fragment and it includes Entity + Type names that are not yet in the target [Temporal Evolution of an + Entity]{.HTML-Keyboard}, add them to the list of Entity Type names of the + target [Temporal Evolution of the Entity]{.HTML-Keyboard}. + +#### 11.2.3.5 Output data + +None. + +### 11.2.4 Delete Attribute from Temporal Evolution of an Entity + +#### 11.2.4.1 Description + +This operation allows deleting an Attribute of the [Temporal Evolution of an +Entity]{.HTML-Keyboard}. The Attribute itself and all its child NGSI-LD elements +shall be deleted. + +#### 11.2.4.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can delete a specific Attribute of the +[Temporal Evolution of an Entity]{.HTML-Keyboard} within an NGSI-LD system as +shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Attribute from Temporal Evolution of an Entity use case +::: + + + +#### 11.2.4.3 Input data + +- Entity ID (URI) of the target [Temporal Evolution of an + Entity]{.HTML-Keyboard} to be modified by removing the target Attribute. +- Target Attribute to be deleted, identified by a name. +- An optional parameter identifying the dataset ( _`datasetId`_) of the target + Attribute instance to be deleted. +- An optional parameter, a flag, (_deleteAll_) indicating whether all target + Attribute instances are to be deleted, regardless of _`datasetId`_. +- An optional JSON-LD _`@context`_. + +#### 11.2.4.4 Behaviour + +- If the target Entity ID is not a valid URI or it is not present, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute name is not a valid name, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing [Temporal Evolution of an Entity]{.HTML-Keyboard} whose id + (URI) is equivalent held locally and no matching registrations apply, then an + error of type [ResourceNotFound]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the input data + is forwarded. For each matching registration: + - If the "Delete Attribute from Temporal Evolution of an Entity" operation is + supported by the matched registration, matching input data is forwarded to + the Registration endpoint. + - If the "Delete Attribute from Temporal Evolution of an Entity" operation is + not supported by the matched registration, this shall result in an error of + type [Conflict]{.HTML-Error} in case the complete "Delete Attribute from + Temporal Evolution of an Entity" failed, or in a partial success if some + parts of it succeeded. + + No further processing is required. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the input data, that input data is also forwarded for remote + processing to matching endpoints. +- If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} exists + locally, implementations shall do the following: + - Apply term expansion as mandated by Clause+++clause-8+++root.2.4 so that the + fully qualified name (URI) associated to the target Attribute is properly + obtained. + - If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} does not + contain the target Attribute then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. + - If the _`deleteAll`_ flag is set + - remove all target Attribute instances from the target Entity. + - Otherwise: + - if a _`datasetId`_ parameter is provided, remove only any target Attribute + instance from the given dataset; + - if no _`datasetId`_ parameter is provided, remove only the default target + Attribute instance _`datasetId`_ from the target Entity. + +#### 11.2.4.5 Output data + +None. + +### 11.2.5 Modify Attribute instance in Temporal Evolution of an Entity + +#### 11.2.5.1 Description + +This operation allows modifying a specific Attribute instance, identified by its +_`instanceId`_, of the [Temporal Evolution of an Entity]{.HTML-Keyboard}. + +This operation enables the correction of wrong information that could have been +previously added to the [Temporal Evolution of an Entity]{.HTML-Keyboard}. + +#### 11.2.5.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can modify a specific Attribute instance, +identified by a given _`instanceId`_, of the [Temporal Evolution of an Entity +]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Modify Attribute Instance in Temporal Evolution of an Entity use case +::: + + + +#### 11.2.5.3 Input data + +- Entity ID (URI) of the target [Temporal Evolution of an + Entity]{.HTML-Keyboard} to be modified by changing an instance of the target + Attribute. +- Target Attribute to be modified, identified by a name. +- Attribute instance to be modified, identified by its _`instanceId`_. +- A JSON-LD document representing an NGSI-LD Fragment of _EntityTemporal_, + including only the new Attribute instance, contained by an Array of exactly + one item. +- An optional JSON-LD _`@context`_. + +#### 11.2.5.4 Behaviour + +- If the target Entity ID is not a valid URI or it is not present, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute name is not a valid name or it is not present, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target _`instanceId`_ is not a valid URI or it is not present, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI) is equivalent held locally and no + matching registrations apply, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the input data + is forwarded. For each matching registration: + - If the "Modify Attribute instance in Temporal Evolution of an Entity" + operation is supported by the matched registration, matching input data is + forwarded to the Registration endpoint. + - If the "Modify Attribute instance in Temporal Evolution of an Entity" + operation is not supported by the matched registration, this shall result in + an error of type [Conflict]{.HTML-Error} in case the complete Modify + Attribute instance in [Temporal Evolution of an Entity]{.HTML-Keyboard} + operation failed, or in a partial success if some parts of it succeeded. + + No further processing is required. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the input data, that input data is also forwarded for remote + processing to matching endpoints. +- If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} exists + locally, implementations shall do the following: + - Apply term expansion as mandated by Clause+++clause-8+++root.2.4 so that the + fully qualified name (URI) associated to the target Attribute is properly + obtained. + - If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} does not + contain the target Attribute then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. + - If for the target Attribute no instance with the specified _`instanceId`_ + exists, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. + - Replace the target Attribute instance identified by the _`instanceId`_ with + the Attribute instance in the _EntityTemporal_ Fragment. The _`createdAt`_ + property of the concerned instance shall remain unchanged, but the + _`modifiedAt`_ property shall be set to the timestamp corresponding to this + modification. + +#### 11.2.5.5 Output data + +None. + +### 11.2.6 Delete Attribute instance from Temporal Evolution of an Entity + +#### 11.2.6.1 Description + +This operation allows deleting one Attribute instance, identified by its +_`instanceId`_, of the [Temporal Evolution of an Entity]{.HTML-Keyboard}. The +Attribute itself and all its child elements shall be deleted. This operation +enables the removal of individual Attribute instances that could have been +previously added to the [Temporal Evolution of an Entity]{.HTML-Keyboard}. + +#### 11.2.6.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can delete an Attribute instance, +identified by a given _`instanceId`_, of the [Temporal Evolution of an +Entity]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Attribute Instance from Temporal Evolution of an Entity use case +::: + + + +#### 11.2.6.3 Input data + +- Entity ID (URI) of the target [Temporal Evolution of an + Entity]{.HTML-Keyboard} to be modified by deleting an instance of the target + Attribute. +- Target Attribute to be deleted, identified by a name. +- Attribute instance to be deleted, identified by its _`instanceId`_. +- An optional JSON-LD _`@context`_. + +#### 11.2.6.4 Behaviour + +- If the target Entity ID is not a valid URI or it is not present, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target Attribute name is not a valid name or it is not present, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the target _`instanceId`_ is not a valid URI or it is not present, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI) is equivalent held locally and no + matching registrations apply, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the input data + is forwarded. For each matching registration: + - If the "Delete Attribute instance from Temporal Evolution of an Entity" + operation is supported by the matched registration, matching input data is + forwarded to the Registration endpoint. + - If the "Delete Attribute instance from Temporal Evolution of an Entity" + operation is not supported by the matched registration, this shall result in + an error of type [Conflict]{.HTML-Error} in case the complete "Delete + Attribute instance from Temporal Evolution of an Entity" failed, or in a + partial success if some parts of it succeeded. + + No further processing is required. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the input data, that input data is also forwarded for remote + processing to matching endpoints. +- If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} exists + locally, implementations shall do the following: + - Apply term expansion as mandated by Clause+++clause-8+++root.2.4 so that the + fully qualified name (URI) associated to the target Attribute is properly + obtained. + - If the target [Temporal Evolution of the Entity]{.HTML-Keyboard} does not + contain the target Attribute then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. + - If for the target Attribute no instance with the specified _`instanceId`_ + exists, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. + - Remove the instance, with the specified _instanceId,_ of the target + Attribute from the target Entity. + +#### 11.2.6.5 Output data + +None. + +### 11.2.7 Delete Temporal Evolution of an Entity + +#### 11.2.7.1 Description + +This operation allows deleting the [Temporal Evolution of an +Entity]{.HTML-Keyboard}. + +#### 11.2.7.2 Use case diagram + +A [Context Producer]{.HTML-Keyboard} can completely delete the [Temporal +Evolution of an Entity]{.HTML-Keyboard} within an NGSI-LD system as shown in +Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Temporal Evolution of an Entity use case +::: + + + +#### 11.2.7.3 Input data + +- Entity ID (URI) of the target [Temporal Evolution of an + Entity]{.HTML-Keyboard} to be deleted. + +#### 11.2.7.4 Behaviour + +- If the target Entity ID is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity because there is + no existing Entity whose id (URI) is equivalent held locally and no matching + registrations apply, then an error of type [ResourceNotFound]{.HTML-Error} + shall be raised. +- If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} matches against the input data, the input data + is forwarded. For each matching registration: + - If the "Delete Temporal Evolution of Entity" operation is supported by the + matched registration, matching input data is forwarded to the Registration + endpoint. + - If the "Delete Temporal Evolution of Entity" operation is not supported by + the matched registration, this shall result in an error of type + [Conflict]{.HTML-Error} in case the complete "Delete Temporal Evolution of + Entity" failed, or in a partial success if some parts of it succeeded. + + No further processing is required. + +- For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that + match against the input data, that input data is also forwarded for remote + processing to matching endpoints. +- If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} exists + locally, the entire [Temporal Evolution of the Entity]{.HTML-Keyboard} shall + be removed. + +#### 11.2.7.5 Output data + +None. + +## 11.3 Temporal context information consumption + +### 11.3.1 Introduction + +Clause+++root.3 describes all operations related to consuming the [Temporal +Evolution of Entities]{.HTML-Keyboard}. + +### 11.3.2 Retrieve Temporal Evolution of an Entity + +#### 11.3.2.1 Description + +This operation allows retrieving the [Temporal Evolution of an +Entity]{.HTML-Keyboard}. + +#### 11.3.2.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve the [Temporal Evolution of an +Entity]{.HTML-Keyboard} (in the form of a temporal representation) from an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Temporal Evolution of an Entity use case +::: + + + +#### 11.3.2.3 Input data + +- Entity ID (URI) of the target [Temporal Evolution of an + Entity]{.HTML-Keyboard} to be retrieved. +- List of Attribute (Properties or Relationships) names to be retrieved + (projection attributes) (optional). +- A restrictive list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + retrieved (projection attributes as defined by Clause+++clause-7+++root.3.2) + (optional). +- An exclusionary list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + removed (projection attributes as defined by Clause+++clause-7+++root.3.2) + (optional). +- An NGSI-LD temporal query as mandated by Clause+++clause-7+++root.2.6 + (optional). +- A parameter (_`lastN`_) conveying that only the last N instances (per + Attribute) within the concerned temporal interval shall be retrieved + (optional). +- An optional JSON-LD context. +- A flag indicating whether to return the location of the [Entity + Map]{.HTML-Keyboard} used within the operation (optional). +- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity + Map]{.HTML-Keyboard} is to be created (optional). +- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching + Entity registrations (optional). +- A _`datasetId`_ parameter that specifies which Attribute instances are to be + selected as defined by Clause+++clause-8+++root.5 (optional). + +#### 11.3.2.4 Behaviour + +- If the Entity ID is not present or it is not a valid URI, then an error of + type [BadRequestData]{.HTML-Error} shall be raised. +- If projection attributes are present and indicate the use of [Linked + Entity]{.HTML-Keyboard} retrieval, an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target Entity, because there + is no existing Entity whose id (URI) is equivalent held locally, and no + matching registrations apply, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- Term to URI expansion of Attribute names shall be observed as mandated by + Clause+++clause-8+++root.2.4. +- The _lastN_ parameter refers to a number, _n_, of Attribute instances which + shall correspond to the last _n_ timestamps (in descending ordering) of the + temporal property (by default _observedAt_) within the concerned temporal + interval. +- Let S be the [Temporal Evolution of the Entity]{.HTML-Keyboard} as mandated by + Clause+++clause-5+++root.2.6.4.2 with the specified Entity ID as it is + available locally. S is empty in case no [Temporal Evolution of the + Entity]{.HTML-Keyboard} is available locally. +- From S, select only those Attribute instances (corresponding to the Attributes + specified by the query or all if none are specified) match the temporal + restrictions imposed by the temporal query (as mandated by + Clause+++clause-7+++root.2.6); i.e. if the time series, for all the concerned + Attributes of an Entity, does not include data corresponding to the temporal + query interval, then such Entity shall be removed from S, thus it shall not + appear in the final result set. Let S1 be this new subset. +- If the ContextBroker implementation supports the use of [Entity + Maps]{.HTML-Keyboard} then: + - If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of + matching Entity registrations is present it shall be retrieved: + - If the resource cannot be found, or the data has expired, a new [Entity + Map]{.HTML-Keyboard} shall be created. + - If the data has not expired, **only** the retrieved Entity Map shall be + used to determine which [Context Source Registrations]{.HTML-Keyboard} + match the Entity ID. + - If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the + request, and no [Entity Map]{.HTML-Keyboard} currently exists, then a new + [Entity Map]{.HTML-Keyboard} shall be created. +- For [Context Source Registrations]{.HTML-Keyboard} that match the Entity ID + and support the "retrieveTemporal" operation (see operations and operation + groups in Clause+++clause-9+++root.2), implementations shall do the following: + - If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an + [Entity Map]{.HTML-Keyboard} entry linked to a [Context Source + Registration]{.HTML-Keyboard} is found, the location of the linked [Entity + Map]{.HTML-Keyboard} shall be passed as part of any forwarded request. + - For any **exclusive**, **redirect** and **inclusive** [Context + Source]{.HTML-Keyboard}, the request is forwarded for remote retrieval by + matching endpoints. and remote Attribute data for the Entity is received. + The result is then merged together with S1 according to the algorithm + defined in Clause+++clause-8+++root.5. + - For any **auxiliary** [Context Source Registrations]{.HTML-Keyboard} the + remote Attribute data received is added to S1 only when the Attribute + instance, whose value of the _`timeproperty`_, which is used for the + temporal query (_`observedAt`_ as default), is not present in any of the + Attribute instances received from elsewhere. + - If an [Entity Map]{.HTML-Keyboard} is in use for this operation, the [Entity + Map]{.HTML-Keyboard}'s linked maps are updated to hold the location of every + [Entity Map]{.HTML-Keyboard} used by the [Context Source + Registrations.]{.HTML-Keyboard} +- For the set of [Attribute Instances]{.HTML-Keyboard} that are in S1, when ) + _`datasetId`_ parameter is provided in the request: + - Filter the Attribute instances based on the _`datasetId`_ parameter, i.e. + keep only the Attribute instances whose _`datasetId`_ is specified. The + default Attribute instance is matched, if ["@none"]{.HTML-Code} is + specified. + - If there is no Attribute instance whose _`datasetId`_ matches the value of + the parameter, remove the complete Attribute from S1. +- From the set of [Attribute Instances]{.HTML-Keyboard} that are in S1, include + in their temporal representation only the Attribute instances (up to + _`lastN`_) corresponding to the query's projection Attributes, or aggregated + values of Attribute instances (if aggregated temporal representation is + requested). + +In the general case, it is not possible to retrieve a set of entities by only +specifying desired Entity identifiers, without further specifying restrictions +on the entities' types or attributes, either explicitly, via selector of Entity +types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. +If the execution of the operation is limited to the local scope (see +Clause+++clause-8+++root.6), no further restrictions have to be provided. + +#### 11.3.2.5 Output data + +A JSON-LD object representing the [Temporal Evolution of the target +Entity]{.HTML-Keyboard} as mandated by Clause+++clause-5+++root.2.6.4.2. + +If a restrictive list of Entity member names is present, every Entity within the +payload body is reduced down to only contain the defined Entity members. + +If an exclusionary list of Entity member names is present, the defined Entity +members listed are removed from each Entity within the payload. + +### 11.3.3 Query Temporal Evolution of Entities + +#### 11.3.3.1 Description + +This operation allows querying the [Temporal Evolution of +Entities]{.HTML-Keyboard} present in an NGSI-LD system. It is similar to the +operation defined by Clause+++clause-10+++root.4.3 (Query Entities) with the +addition of a temporal query. + +#### 11.3.3.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve the Temporal Evolution of a +set of Entities which matches a specific query from an NGSI-LD system as shown +in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Query Temporal Evolution of Entities use case +::: + + + +#### 11.3.3.3 Input data + +- An NGSI-LD temporal query as mandated by Clause+++clause-7+++root.2.6. +- A reference to a JSON-LD _`@context`_ (optional). +- A selector of Entity types as specified by Clause+++clause-7+++root.2.2 + (optional). Both type name (short hand string) and fully qualified type name + (URI) are allowed. +- A restrictive list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + retrieved (projection attributes as defined by Clause+++clause-7+++root.3.2) + (optional). +- An exclusionary list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + removed (projection attributes as defined by Clause+++clause-7+++root.3.2) + (optional). +- A list (one or more) of Entity identifiers (optional). +- A list (one or more) of Attribute names of which at least one shall exist in + order for an Entity to be selected, and also used as query projection + attributes (optional). +- An id pattern as a regular expression (optional). +- An NGSI-LD query (to filter out Entities by Attribute values) as per + Clause+++clause-7+++root.2.3 (optional). +- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as + mandated by Clause+++clause-7+++root.2.4 (optional). +- A NGSI-LD Scope query (to filter out Entities based on their Scope) as + mandated by Clause+++clause-7+++root.2.5 (optional). +- An NGSI-LD query (called context source filter, to filter out [Context + Sources]{.HTML-Keyboard} by the values of properties that describe them) as + per Clause+++clause-7+++root.2.3 (optional). +- A limit to the number of Entities to be retrieved. See + Clause+++clause-7+++root.4.2. +- A parameter (lastN) conveying that only the last N instances (per Attribute) + within the concerned temporal interval shall be retrieved (optional). +- A specified language filter as per Clause+++clause-7+++root.2.7 (optional). +- A list (one or more) of Attribute names whose values shall be expanded to URIs + prior to executing a query (optional). +- A flag indicating whether to return the location of the [Entity + Map]{.HTML-Keyboard} used within the operation (optional). +- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity + Map]{.HTML-Keyboard} is to be created (optional). +- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching + Entity registrations (optional). +- A _`datasetId`_ parameter that specifies which Attribute instances are to be + selected as defined by Clause+++clause-8+++root.5 (optional). +- A preferred ordering of Entities retrieved - only the Entity member name + ["id"]{.HTML-Code} can be used (Entity ordering attributes as defined by + Clause+++clause-7+++root.6.2) (optional). +- A preferred collation setting to be used when applying ordering of Entities + (optional). +- A flag indicating whether split Entities are to be expected, i.e. Entities + whose information is distributed across different Context Sources (optional). + +In the general case, it is not possible to retrieve a set of entities by only +specifying desired Entity identifiers, without further specifying restrictions +on the entities' types or attributes, either explicitly, via selector of Entity +types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. +If the execution of the operation is limited to the local scope (see +Clause+++clause-8+++root.6 ), no further restrictions have to be provided. + +#### 11.3.3.4 Behaviour + +- If a temporal query is not provided then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- At least one of the following input data shall be provided: a. selector of + Entity Types; b. list of Attribute names, including at least one non-system + Attribute; c. NGSI-LD Query, including at least one non-system Attribute; d. + NGSI-LD GeoQuery; e. local scope (see Clause+++clause-8+++root.6). + + If none of the above is provided, then an error of type + [BadRequestData]{.HTML-Error} + +- If projection attributes or filter conditions indicate the use of [Linked + Entity ]{.HTML-Keyboard} retrieval, an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the list of Entity identifiers includes a URI which it is not valid, or the + query, geoquery or context source filter are not syntactically valid (as per + the referred Clause+++clause-7+++root.2.3 and Clause+++clause-7+++root.2.4) an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the ordering parameter is present and the execution of the operation is not + limited to the local scope (see Clause+++clause-8+++root.6) then an error of + type [BadRequestData]{.HTML-Error} shall be raised. +- If the ordering parameter is present and refers an entity name other than + ["id"]{.HTML-Code}, then an error of type [BadRequestData]{.HTML-Error} shall + be raised. +- If a preferred collation setting is present and it does not conform to a valid + ICU collation (see IETF RFC 6067 \[n.36\]) then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- Term to URI expansion of type and Attribute names shall be observed mandated + by Clause+++clause-8+++root.2.4. +- If a list of Attribute names whose values shall be expanded to URIs has been + supplied, JSON-LD type coercion shall be performed as mandated by + Clause+++clause-8+++root.2.4. +- The _lastN_ parameter refers to a number, _n_, of Attribute instances which + shall correspond to the last _n_ timestamps (in descending ordering) of the + temporal property (by default _observedAt_) within the concerned temporal + interval. +- Otherwise, + - Let S be the set of selected Entities i.e. the query result set. + - If split entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split entities, and local scope + is not specified, implementations shall run a query that shall return an + Entity Array containing all the Entities found locally, that meet all of the + following conditions (given the respective parameter is provided): + - If id(s) is provided, keep in S only those Entities whose id is equivalent + to any of the id(s) passed as a parameter. + - If an id pattern is provided, keep in S only those Entities whose id + matches the id pattern. + - If a selector of Entity Types is provided, keep in S only those Entities + whose Entity Type names match the selector of Entity Types. + - From S, select only those Entities any of whose Attribute instances + (corresponding to the Attributes specified by the query or all if none are + specified) match the temporal restrictions imposed by the temporal query + (as mandated by Clause+++clause-7+++root.2.6); i.e. if the time series, + for all the concerned Attributes of an Entity, does not include data + corresponding to the temporal query interval, then such Entity shall be + removed from S, thus it shall not appear in the final result set. Let S4 + be this new subset. + + - Implementations shall run a query that shall return the Temporal Evolution + of the matching Entities (all Entities stored locally, in case only a local + scope is specified); the logical steps to select the final result set of + Entities, and the Attribute instances included as part of their temporal + representation, are enumerated as follows: + - If id(s) is provided, keep in S only those Entities whose id is equivalent + to any of the id(s) passed as a parameter. + - If an id pattern is provided, keep in S only those Entities whose id + matches the id pattern. + - If a selector of Entity Types is provided, keep in S only those Entities + whose Entity Type names match the selector of Entity Types. + - From S, select only those Entities any of whose Attribute instances + (corresponding to the Attributes specified by the query or all if none are + specified) match the temporal restrictions imposed by the temporal query + (as mandated by Clause+++clause-7+++root.2.6); i.e. if the time series, + for all the concerned Attributes of an Entity, does not include data + corresponding to the temporal query interval, then such Entity shall be + removed from S, thus it shall not appear in the final result set. Let S1 + be this new subset. + - If a values filter query is provided, from S1, select those Entities whose + Attribute instances (during the interval defined by the temporal query) + meet the matching conditions specified by the query (as mandated by + Clause+++clause-7+++root.2.3); i.e. the values filter query shall be + checked against all the Attribute instances resulting from the initial + filtering performed by the temporal query. Let S2 be this new subset. + - If no values filter query is provided, then S2 is equal to S1. + - If geoquery is present, from S2, select those Entities whose _GeoProperty_ + instances meet the geospatial restrictions imposed by the geoquery (as + mandated by Clause+++clause-7+++root.2.4); those geospatial restrictions + shall be checked against the _GeoProperty_ instances that are within the + interval defined by the temporal query. Let S3 be this new subset. + - If no geoquery is provided, then S3 is equal to S2. + - If the Scope query is present, from S3, select those Entities whose Entity + Scope instances match the Scope query (as mandated by + Clause+++clause-7+++root.2.5, for an example see [i.16] ~annex A.16). Let + S4 be the new subset. + - If no Scope query is provided, then S4 is equal to S3. + +- If the ContextBroker implementation supports the use of [Entity + Maps]{.HTML-Keyboard} then: + - If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of + matching Entity registrations is present it shall be retrieved: + - If the resource cannot be found, or the data has expired, a new [Entity + Map]{.HTML-Keyboard} shall be created. + - If the data has not expired, only the retrieved [Entity + Map]{.HTML-Keyboard} shall be used to determine which Context Source + Registrations match the Entity ID. + - If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the + request, and no [Entity Map]{.HTML-Keyboard} currently exists, then a new + [Entity Map]{.HTML-Keyboard} shall be created. +- Unless local scope is specified (see Clause+++clause-8+++root.6), for [Context + Source Registrations]{.HTML-Keyboard} that match the query and support the + "queryTemporal" operation (see operations and operation groups in + Clause+++clause-9+++root.2), implementations shall do the following: + - If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an + [Entity Map]{.HTML-Keyboard} entry linked to a Context Source Registration + is found, the location of the [Entity Map]{.HTML-Keyboard} shall be passed + as part of the forwarded request. + - If split entities flag is explicitly set to true or, if not explicitly + set, the default setting of the deployment allows split entities, the + filters (filter conditions specified by the query, geospatial restrictions + imposed by the geoquery, Scope query, Attributes) shall be removed before + forwarding the request. These filters then have to be applied after the + Entity information from different Context Sources and local information, + if there is any, has been aggregated. + - For any **exclusive**, **redirect** and **inclusive** [Context Source + Registrations]{.HTML-Keyboard} that match against the query, the request is + forwarded for remote querying by matching endpoints. The result of each + remote query is an Entity Array. The returned result is then merged into S4 + according to the algorithm defined in Clause+++clause-8+++root.5. + - For any **auxiliary** [Context Source Registrations]{.HTML-Keyboard} that + match against the query, the request is forwarded for remote querying by + matching endpoints. Data from the Entity Array received is merged only into + S4 when an Attribute instance, whose value of the timeproperty used for the + temporal query, is not already present in S4. +- If split entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split entities, and local scope + is not specified, the following filters have to be applied on the aggregated + Entities: + - If a values filter query is provided, from S4, select those Entities whose + Attribute instances (during the interval defined by the temporal query) meet + the matching conditions specified by the query (as mandated by + Clause+++clause-7+++root.2.3); i.e. the values filter query shall be checked + against all the Attribute instances resulting from the initial filtering + performed by the temporal query. Let S5 be this new subset. + - If no values filter query is provided, then S5 is equal to S4. + - If geoquery is present, from S5, select those Entities whose GeoProperty + instances meet the geospatial restrictions imposed by the geoquery (as + mandated by Clause+++clause-7+++root.2.4); those geospatial restrictions + shall be checked against the GeoProperty instances that are within the + interval defined by the temporal query. Let S6 be this new subset. + - If no geoquery is provided, then S6 is equal to S5. + - If the Scope query is present, from S6, select those Entities whose Entity + Scope instances match the Scope query (as mandated by + Clause+++clause-7+++root.2.5, for an example see [i.16] ~annex A.16). Let S7 + be the new subset. + - If no Scope query is provided, then S7 is equal to S6. +- Otherwise S7 is equal to S4. +- If a _`datasetId`_ parameter is provided, from S7, for all Entities, filter + the Attribute instances based on the _datasetIds_ specified in the parameter, + i.e. keep only the Attribute instances whose _`datasetId`_ is specified. The + default Attribute instance is matched, if ["@none"]{.HTML-Code} is + specified. Remove all Attributes without remaining Attribute instances. Let S8 + be this new subset. +- If no _`datasetId`_ is provided then S8 equals to S7. +- From the set of Entities that are in S8, include in their temporal + representation only the Attribute instances (up to _lastN_) corresponding to + the query's projection Attributes, or aggregated values of Attribute instances + (if aggregated temporal representation is requested), and which meet the + temporal, query and geoquery restrictions. + + If an aggregated temporal representation is requested and any of the requested + Attributes is not eligible for at least one of the aggregation methods + specified in the request parameters, then an error of type + [InvalidRequest]{.HTML-Error} shall be raised. + +- Pagination logic shall be in place as mandated by + Clause+++clause-7+++root.4.2. +- If in the process of obtaining the query result it is necessary to issue a + [Context Source]{.HTML-Keyboard} discovery operation, the same [Context + Source]{.HTML-Keyboard} filter input parameter (if present) shall be + propagated. + +#### 11.3.3.5 Output Data + +A JSON-LD array representing the matching entities as defined by +Clause+++clause-5+++root.2.6.7.4 and selected according to the behaviour +described by Clause+++clause-11+++root.3.3.4. + +If Entity ordering is specified (see Clause+++clause-7+++root.6.2), then the +JSON-LD array returned shall be ordered according to the member names specified. + +If a restrictive list of Entity member names is present, every Entity within the +payload body is reduced down to only contain the defined Entity members. + +If an exclusionary list of Entity member names is present, the defined Entity +members listed are removed from each Entity within the payload. diff --git a/md/clause-12.md b/md/clause-12.md new file mode 100644 index 0000000000000000000000000000000000000000..dee41f8f4a28c58519202815e9d3f1e72661d804 --- /dev/null +++ b/md/clause-12.md @@ -0,0 +1,786 @@ +# 12 Registry API operations + +## 12.1 Introduction + +Clause+++root describes all operations related to the Registry API. It allows +for registering [Context Sources]{.HTML-Keyboard} and managment of [Context +Source Registrations]{.HTML-Keyboard}. + +## 12.2 Context Source Registration + +### 12.2.1 Introduction + +This clause defines all operations that [Context Broker]{.HTML-Keyboard} +implementations shall offer to ensure the discovery, operation and management of +[Context Sources]{.HTML-Keyboard}. + +### 12.2.2 Register Context Source + +#### 12.2.2.1 Description + +This operation allows registering a context source within an NGSI-LD system. + +#### 12.2.2.2 Use case diagram + +A [Context Provider]{.HTML-Keyboard} can register one or more [Context +Sources]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Register context source use case +::: + + + +#### 12.2.2.3 Input data + +A data structure conforming to the _CSourceRegistration_ data type as mandated +by Clause+++clause-5+++5.2.6.5.3. + +#### 12.2.2.4 Behaviour + +Implementations shall generally exhibit the behaviour described in +Clause+++clause-10+++10.2.2.4, but instead of any type of entities only [Context +Source Registrations]{.HTML-Keyboard} can be provided and the following +exceptions shall apply: + +- If the data types and restrictions expressed by Clause+++clause-5+++5.2.6.5.3 + are not met by the [Context Source Registration]{.HTML-Keyboard}, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If a _`contextSourceInfo`_ array is defined and the restrictions expressed by + Clause+++clause-9+++9.5.2 are not met by the [Context Source + Registration]{.HTML-Keyboard}, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the [Context Source]{.HTML-Keyboard} to be registered has its _`mode`_ + property defined as **exclusive**, the following additional restrictions + apply: + - If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} already matches against the Entity ID (URI) + and any of the Attributes defined in the registration, an error of type + [Conflict]{.HTML-Error} shall be raised. + - If an Entity already exists for the supplied Entity ID (URI) and the + existing Entity contains any of the Attributes defined in the registration, + an error of type [Conflict]{.HTML-Error} shall be raised. + +- If the [Context Source]{.HTML-Keyboard} to be registered has its _`mode`_ + property defined as **redirect**, the following additional restriction + applies: + - If an existing Entity already matches the [Context Source + Registration]{.HTML-Keyboard}, an error of type [Conflict]{.HTML-Error} + shall be raised. + +- If the [Context Source]{.HTML-Keyboard} to be registered has its _`mode`_ + property defined as **auxiliary**, the following additional restriction + applies: + - If the _operations_ property is not defined as one of: + ["retrieveOps"]{.HTML-Code}, ["retrieveEntity"]{.HTML-Code} or + ["queryEntity",]{.HTML-Code} or a combination thereof, an error of type + [BadRequestData]{.HTML-Error} shall be raised. + +- If the property _`expiresAt`_ is not defined then the [Context Source + Registration]{.HTML-Keyboard} shall last forever (or until it is deleted from + the system). +- If _`expiresAt`_ is a date and time in the past, an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If _`expiresAt`_ is a date and time in the future, implementations shall + delete the Registration when this point in time is reached. +- If the NGSI-LD endpoint knows about this [Context Source Registration, + ]{.HTML-Keyboard} as there is an existing [Context Source Registration + ]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type + [AlreadyExists]{.HTML-Error} shall be raised. +- If the subscription document does not include a [Context Source + Registration]{.HTML-Keyboard} identifier, a new identifier (URI) shall be + automatically generated by the implementation. +- Implementations shall add the concerned [Context Source + Registration]{.HTML-Keyboard} and return an 'ok' response together with a + registration identifier (_`id`_). +- This _`id`_ shall be used if NGSI-LD clients need to manage the registration + later. + +#### 12.2.2.5 Output data + +A URI identifying the newly created ContextSourceRegistration. + +### 12.2.3 Update Context Source Registration + +#### 12.2.3.1 Description + +This operation allows updating a [Context Source Registration]{.HTML-Keyboard} +in an NGSI-LD system. + +#### 12.2.3.2 Use case diagram + +A [Context Provider]{.HTML-Keyboard} can update a [Context Source +Registration]{.HTML-Keyboard} in an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Update context source registration use case +::: + + + +#### 12.2.3.3 Input data + +- [Context Source Registration]{.HTML-Keyboard} identifier (URI), the target + [Context Source Registration]{.HTML-Keyboard}. +- A JSON-LD document representing a [Context Source + Registration]{.HTML-Keyboard} Fragment (Clause+++clause-5+++5.4). + +#### 12.2.3.4 Behaviour + +- If the target [Context Source Registration]{.HTML-Keyboard} id (_`id`_) is not + present or it is not a valid URI, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If a "contextSourceInfo" array is defined and the restrictions expressed by + Clause+++clause-9+++9.5.2 are not met by the [Context Source + Registration]{.HTML-Keyboard}, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD System does not know about the target [Context Source + Registration]{.HTML-Keyboard}, because there is no existing [Context Source + Registration]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- Execute the behaviour defined in Clause+++clause-8+++8.2.3 on JSON-LD + validation. +- If the data types and restrictions expressed by Clause+++clause-5+++5.2.6.5.3 + are not met by the [Context Source Registration]{.HTML-Keyboard} _Fragment_, + then an error of type _BadRequestData_ shall be raised. +- Term to URI expansion of Attribute names shall be observed as mandated by + Clause+++clause-8+++8.2.4. +- If the [Context Source Registration]{.HTML-Keyboard} to be updated has its + _`mode`_ property defined as **exclusive**, the following additional + restrictions apply: + - If an **exclusive** or **redirect** [Context Source + Registration]{.HTML-Keyboard} already matches against the Entity ID (URI) + and any of the Attributes defined in the registration, an error of type + [Conflict]{.HTML-Error} shall be raised. + - If an Entity already exists for the supplied Entity ID (URI) and the + existing Entity contains any of the Attributes defined in the registration, + an error of type [Conflict]{.HTML-Error} shall be raised. + +- If the [Context Source Registration]{.HTML-Keyboard} to be updated has its + _`mode`_ property defined as **redirect**, the following additional + restriction applies: + - If an existing Entity already matches the [Context Source + Registration]{.HTML-Keyboard}, an error of type [Conflict]{.HTML-Error} + shall be raised. + +- If the [Context Source]{.HTML-Keyboard} to be updated has its _`mode`_ + property defined as **auxiliary**, the following additional restriction + applies: + - If the [operations]{.HTML-Code} property is not defined as one of: + ["retrieveOps"]{.HTML-Code}, ["retrieveEntity"]{.HTML-Code} or + ["queryEntity"]{.HTML-Code}, an error of type [BadRequestData]{.HTML-Error} + shall be raised. + +- Then, implementations shall modify the target [Context Source + Registration]{.HTML-Keyboard} as mandated by Clause+++clause-8+++8.4.2. + +#### 12.2.3.5 Output data + +None. + +### 12.2.4 Delete Context Source Registration + +#### 12.2.4.1 Description + +This operation allows deleting a [Context Source Registration]{.HTML-Keyboard} +from an NGSI-LD system. + +#### 12.2.4.2 Use case diagram + +A [Context Provider]{.HTML-Keyboard} can delete a [Context Source +Registration]{.HTML-Keyboard} from an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete context source registration use case +::: + + + +#### 12.2.4.3 Input data + +Registration identifier (URI) of the [Context Source +Registration]{.HTML-Keyboard} to be deleted (target registration). + +#### 12.2.4.4 Behaviour + +- If the target [Context Source Registration]{.HTML-Keyboard} id is not present + or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} + shall be raised. +- If the NGSI-LD endpoint does not know about the target context source + registration, because there is no existing [Context Source + Registration]{.HTML-Keyboard} whose id (URI) is equivalent, then an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- Otherwise the [Context Source Registration]{.HTML-Keyboard} shall be removed. + +#### 12.2.4.5 Output data + +None. + +## 12.3 Context Source discovery + +### 12.3.1 Introduction + +### 12.3.2 Retrieve Context Source Registration + +#### 12.3.2.1 Description + +This operation allows retrieving a specific [Context Source +Registration]{.HTML-Keyboard} from an NGSI-LD system. + +#### 12.3.2.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} or a [Context Provider]{.HTML-Keyboard} can +retrieve a specific [Context Source Registration]{.HTML-Keyboard} from an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve context source registration use case +::: + + + +#### 12.3.2.3 Input data + +[Context Source Registration]{.HTML-Keyboard} identifier (id) of the context +source registration to be retrieved (target registration). + +#### 12.3.2.4 Behaviour + +- If the [Context Source Registration]{.HTML-Keyboard} id (_`id`_) is not + present or it is not a valid URI, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about the target [Context Source + Registration]{.HTML-Keyboard}, because there is no existing [Context Source + Registration]{.HTML-Keyboard} whose id (URI) is equivalent, then an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- Term to URI expansion of Attribute names shall be observed as mandated by + Clause+++clause-8.2.4. +- Otherwise return a JSON-LD object representing the [Context Source + Registration]{.HTML-Keyboard} as mandated by Clause+++clause-5+++5.2.6.5.3. + +#### 12.3.2.5 Output data + +A JSON-LD object representing the target [Context Source +Registration]{.HTML-Keyboard} as mandated by Clause+++clause-5+++5.2.6.5.3. + +### 12.3.3 Query Context Source Registrations + +#### 12.3.3.1 Description + +This operation allows discovering [Context Source Registrations]{.HTML-Keyboard} +from an NGSI-LD system. The behaviour of the discovery of context source +registrations differs significantly from the querying of entities as described +in Clause+++clause-10+++10.4.3. The approach is that the client submits a query +for entities as described in clause 5.7.2, but instead of receiving the Entity +information, it receives a list of [Context Source +Registrations]{.HTML-Keyboard} describing [Context Sources]{.HTML-Keyboard} that +possibly have some of the requested Entity information. This means that the +requested Entities and Attributes are matched against the 'information' property +as described in Clause+++clause-9+++9.4. + +If no temporal query is present, only [Context Source +Registrations]{.HTML-Keyboard} for [Context Sources]{.HTML-Keyboard} providing +latest information, i.e. without specified time intervals, are considered. If a +temporal query is present only [Context Source Registrations]{.HTML-Keyboard} +with matching time intervals, i.e. _`observationInterval`_ or +_`managementInterval`_, are considered. + +#### 12.3.3.2 Use case diagram + +A _Context Consumer_ can discover [Context Source Registrations]{.HTML-Keyboard} +that may be able to provide (part of) the context information specified in the +query from an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Discover context source registrations use case +::: + + + +#### 12.3.3.3 Input data + +- A reference to a JSON-LD _`@context`_ (optional). +- A selector of Entity types as specified by Clause+++clause-7+++7.2.2. Both + type name (short hand string) and fully qualified type name (URI) are allowed + (optional). +- A list (one or more) of Entity identifiers (optional). +- A list (one or more) of Attribute names (called query projection attributes) + (optional). +- An id pattern as a regular expression (optional). +- An NGSI-LD query (to filter out Entities by Attribute values, used here to + identify relevant attributes) as per Clause+++clause-7+++7.2.3 (optional). +- An NGSI-LD geoquery (to filter out Entities by spatial relationships, used + here to identify relevant GeoProperties and for geographical scoping) as per + Clause+++clause-7+++7.2.4 (optional). +- In the case of GeoJSON representation: + - The name of the _GeoProperty_ attribute to use as the geometry for the + GeoJSON representation as mandated by Clause+++clause-5+++5.3.3 (optional). + - A _datasetId_ specifying which instance of the value is to be selected if + the _GeoProperty_ value has multiple instances as defined by + Clause+++clause-8+++8.5. (optional). + +- An NGSI-LD temporal query as per Clause+++clause-7+++7.2.6(optional). +- An NGSI-LD context source query as per Clause+++clause-7+++7.2.3 (optional). +- A NGSI-LD Scope query as mandated by Clause+++clause-7+++7.2.5 (optional). +- A limit to the number of [Context Source Registrations]{.HTML-Keyboard} to be + retrieved. See Clause+++clause-7+++7.4.2. +- A specified language filter as per Clause+++clause-7+++7.2.7 (optional). + +It is not possible to retrieve a set of [Context Source +Registrations]{.HTML-Keyboard} related to entities by only specifying desired +Entity identifiers, without further specifying restrictions on the entities' +types or attributes, either explicitly, via lists of Entity types or of +Attribute names, or implicitly, within an NGSI-LD query or geoquery. + +#### 12.3.3.4 Behaviour + +- Execute the behaviour defined in Clause+++clause-8+++8.2.3 on JSON-LD + validation. +- At least one of the following input data shall be provided: + + + + a. selector of Entity Types; + b. list of Attribute names; + c. NGSI-LD Query; + d. NGSI-LD GeoQuery. + + + +- If none of them is provided, then an error of type + [BadRequestData]{.HTML-Error} with a _list of Attribute names_ + +- If the list of Entity identifiers includes a URI which it is not valid, or the + query, geoquery or temporal query are not syntactically valid (as per + Clause+++clause-7+++2.3, 4.Clause+++clause-7+++2.4 and + Clause+++clause-7+++2.6) an error of type [BadRequestData]{.HTML-Error} shall + be raised. +- Term to URI expansion of type and Attribute names shall be performed, as + mandated by Clause+++clause-8.2.4. +- Otherwise, implementations shall run a query that shall return context source + registrations that meet **all** the applicable conditions: + +- If present, the entity specification in the query consisting of a combination + of entity type selector and entity id/entity id pattern (optional) matches an + _EntityInfo_ specified in a _RegistrationInfo_ of the information property in + a context source registration. If there is no _EntityInfo_ specified in the + _RegistrationInfo_, the entity specification is considered matching. This + matching is further described in Clause+++clause-9+++9.4. +- If present, at least one Attribute name specified in the query matches one + Property or Relationship in the _RegistrationInfo_ element of the information + property in a context source registration. If no Properties or Relationships + are specified in the _RegistrationInfo_, the Attribute names are considered + matching. This matching is further described in Clause+++clause-9+++9.4. +- If present, the geoquery is matched against the _GeoProperty_ identified in + the geoquery. If no _GeoProperty_ is specified in the geoquery, the default + property is _location_. The geoquery matches the _GeoProperty_ specified in + the [Context Source Registration]{.HTML-Keyboard}, if the location directly + matches or if the location possibly contains locations that would match the + geoquery. +- If no temporal query is present, only [Context Source + Registrations]{.HTML-Keyboard} for [Context Sources]{.HTML-Keyboard} providing + latest information, i.e. without specified time intervals, are considered. +- If a temporal query is present, only [Context Source + Registrations]{.HTML-Keyboard} with specified time intervals, i.e. + _observationInterval_ or _`managementInterval`_ are considered. If the + _`timeproperty`_ is _observedAt_ or no _`timeproperty`_ is specified in the + temporal query (default: _observedAt_), the temporal query is matched against + the _`observationInterval`_ (if present). If the _`timeproperty`_ is + _createdAt_, _modifiedAt_ or _deletedAt_, the temporal query is matched + against the _`managementInterval`_ (if present). If the relevant interval is + not present, there is no match: + + - The semantics of the match is that the _`timeAt`_ in the case of the + ["before"]{.HTML-Code} and ["after"]{.HTML-Code} relation is contained in or + is an endpoint of a time period included in the specified time interval. In + the case of the ["between"]{.HTML-Code} relation there is a match if there + is an overlap between the interval specified by the _`timeAt`_ and + _`endTimeAt`_ and the specified time interval. + +- If present, the conditions specified by the context source query filter match + the respective [Context Source]{.HTML-Keyboard} Properties (as mandated by + Clause+++clause-7+++7.2.3). +- If present, the Scope query (as mandated by Clause+++clause-7+++7.2.5) is + matched against the _`scope`_ property. + +- Pagination logic shall be in place as mandated by Clause+++clause-7+++7.4.2. + +#### 12.3.3.5 Output data + +A JSON-LD array of matching [Context Source Registrations]{.HTML-Keyboard} as +defined by Clause+++clause-5+++5.2.6.5.3. Instead of the original [Context +Source Registration]{.HTML-Keyboard} which may contain a lot of irrelevant +information, implementations should return filtered [Context Source +Registrations]{.HTML-Keyboard}, which only contain context source registration +information relevant for the query, in particular only matching +_RegistrationInfo_ elements. + +## 12.4 Context Source Registration Subscription + +### 12.4.1 Introduction + +[Context Source Registration]{.HTML-Keyboard} Subscriptions in general work like +context information subscriptions; however, instead of resulting in +notifications with context information, the notifications contain [Context +Source Registrations]{.HTML-Keyboard} describing [Context +Sources]{.HTML-Keyboard} that can potentially provide the requested context +information. If no temporal query is present, only [Context Source +Registrations]{.HTML-Keyboard} for [Context Sources]{.HTML-Keyboard} providing +latest information, i.e. without such time intervals, are considered. If a +temporal query is present only [Context Source Registrations]{.HTML-Keyboard} +with matching time intervals, i.e. _observationInterval_ or +_`managementInterval`_, are considered. + +### 12.4.2 Create Context Source Registration Subscription + +#### 12.4.2.1 Description + +This operation allows creating a new [Context Source +Registration]{.HTML-Keyboard} Subscription. + +#### 12.4.2.2 Use case diagram + +A [Context Source]{.HTML-Keyboard} _Subscriber_ can subscribe to a new [Context +Source Registration]{.HTML-Keyboard} as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Subscribe Context Source Registration use case +::: + + + +#### 12.4.2.3 Input + +- A data structure (represented in JSON-LD) conforming to the Subscription data + type as mandated by Clause+++clause-5+++5.2.6.5.2. + +#### 12.4.2.4 Behaviour + +- The behaviour shall be as described in Clause+++clause-10+++10.5.2.4, + restricted to the local case (where Subscriptions cannot be received from + remote Brokers), with the following exceptions: + - If all checks described in Clause+++clause-10+++10.5.2.4 pass, + implementations shall add a new [Context Source + Registration]{.HTML-Keyboard} Subscription. The parameters of the created + subscription shall be configured as described in + Clause+++clause-5+++5.2.6.5.2. + - Instead of directly matching the entities and watched Attributes from the + Subscription with the [Context Source]{.HTML-Keyboard} registrations, the + entities specified in the subscription, the watched Attributes and the + Attributes specified in the notification parameter are matched against the + respective _`information`_ property of the [Context Source]{.HTML-Keyboard} + registrations. If either the watched Attributes or the Attributes in the + notification are not present or of length 0, all possible Attributes (if + present in the [Context Source Registrations]{.HTML-Keyboard}) for matching + entities match. This matching is further described in + Clause+++clause-9+++9.4. + - If present, the geoquery in the _`geoQ`_ element is matched against the + _GeoProperty_ of the subscription identified in the _`geoQ`_ element. If no + _GeoProperty_ is specified in the geoquery, the default property is + [location]{.HTML-Keyboard}. The geoquery matches the _GeoProperty_ specified + in the [Context Source Registration]{.HTML-Keyboard}, if the location + directly matches or if the location possibly contains locations that would + match the geoquery. + - If no temporal query is present in the _`temporalQ`_ element, only [Context + Source Registrations]{.HTML-Keyboard} for [Context Sources]{.HTML-Keyboard} + providing latest information, i.e. without specified time intervals for + _`observationInterval`_ or _`managementInterval`_, are considered. + - If a temporal query in the _`temporalQ`_ element is present, only [Context + Source Registrations]{.HTML-Keyboard} with specified time intervals are + considered. If the _`timeproperty`_ is ["observedAt"]{.HTML-Code} or no + _`timeproperty`_ is specified in the temporal query (default: _observedAt_), + the temporal query is matched against the _`observationInterval`_ (if + present). If the _`timeproperty`_ is ["createdAt"]{.HTML-Code}, + ["modifiedAt"or "deletedAt",]{.HTML-Code} the temporal query is matched + against the _`managementInterval`_ (if present). If the relevant interval is + not present, there is no match: + - The semantics of the match is that the _`timeAt`_ in the case of the + ["before"]{.HTML-Code} and ["after"]{.HTML-Code} relation is contained in + or is an endpoint of a time period included in the specified time + interval. In the case of the ["between"]{.HTML-Code} relation there is a + match if there is an overlap between the interval specified by the + _`timeAt`_ and _`endTimeAt`_ and the specified time interval. + + - If present, the conditions specified by the context source filter match the + respective [Context Source]{.HTML-Keyboard} Properties (as mandated by + Clause+++clause-7+++7.2.3). + +- If the subscription defines a _`timeInterval`_ term, a _CsourceNotification_ + (Clause+++clause-5+++5.2.6.9.4) with all matching [Context Source + Registrations]{.HTML-Keyboard} shall be sent periodically, initially on + subscription and when the time interval (in seconds) specified in such value + field is reached, independent of any changes to the set of [Context + Source]{.HTML-Keyboard} registrations. +- If _`timeInterval`_ is not defined, initially on subscription and whenever + there is a change of a matching [Context Source Registration]{.HTML-Keyboard} + (creation, update, deletion), implementations shall post a new + _CsourceNotification_ to the endpoint specified in the notification parameters + informing about this change by providing the [Context Source + Registration]{.HTML-Keyboard}(s) together with the appropriate trigger reason + in the _`triggerReason`_ member. +- If present, the conditions specified by the context source query match the + respective [Context Source]{.HTML-Keyboard} Properties (as mandated by clause + 4.9). +- If present, the Scope query (as mandated by Clause+++clause-7+++7.2.5) is + matched against the _`scope`_ property. + +#### 12.4.2.5 Output data + +A URI identifying the newly created Subscription. + +### 12.4.3 Update Context Source Registration Subscription + +#### 12.4.3.1 Description + +This operation allows updating an existing [Context Source +Registration]{.HTML-Keyboard} Subscription. + +#### 12.4.3.2 Use case diagram + +A context source subscriber can update a [Context Source +Registration]{.HTML-Keyboard} Subscription as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Update Context Source Registration Subscription use case +::: + + + +#### 12.4.3.3 Input data + +- Subscription identifier (URI), the target [Context Source + Registration]{.HTML-Keyboard} Subscription. +- A JSON-LD document representing a Subscription Fragment. + +#### 12.4.3.4 Behaviour + +- If the Subscription Id is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the data types and restrictions expressed by Clause+++clause-5+++5.2.6.5.2 + are not met by the Subscription Fragment, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- Then, implementations shall modify the target subscription as mandated by + Clause+++clause-8+++8.4.2. +- Finally, send a notification with all currently matching [Context Source + Registrations]{.HTML-Keyboard}. + +#### 12.4.3.5 Output data + +None. + +### 12.4.4 Retrieve Context Source Registration Subscription + +#### 12.4.4.1 Description + +This operation allows retrieving an existing [Context Source +Registration]{.HTML-Keyboard} Subscription. + +#### 12.4.4.2 Use case diagram + +A [Context Source]{.HTML-Keyboard} subscriber can retrieve a specific [Context +Source Registration]{.HTML-Keyboard} Subscription as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Context Source Registration Subscription use case +::: + + + +#### 12.4.4.3 Input data + +Id (URI) of the subscription to be retrieved (target subscription). + +#### 12.4.4.4 Behaviour + +- If the subscription Id is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the identifier provided does not correspond to any existing subscription in + the system then an error of type [ResourceNotFound]{.HTML-Error} shall be + raised. +- Otherwise implementations shall query the [Context Source + Registration]{.HTML-Keyboard} Subscriptions and obtain the subscription data + to be returned to the caller. + +#### 12.4.4.5 Output data + +A JSON-LD object representing the subscription details as mandated by clause +5.2.12. + +### 12.4.5 Query Context Source Registration Subscriptions + +#### 12.4.5.1 Description + +This operation allows querying existing [Context Source +Registration]{.HTML-Keyboard} Subscriptions. + +#### 12.4.5.2 Use case diagram + +A context source subscriber can query all existing [Context Source +Registration]{.HTML-Keyboard} Subscriptions as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Query Context Source Registration Subscriptions use case +::: + + + +#### 12.4.5.3 Input data + +A limit to the number of [Context Source Registration]{.HTML-Keyboard} +Subscriptions to be retrieved. See Clause+++clause-7+++7.4.2. + +#### 12.4.5.4 Behaviour + +- The NGSI-LD System shall list all the existing [Context Source + Registration]{.HTML-Keyboard} Subscriptions. +- Pagination logic shall be in place as mandated by Clause+++clause-7+++7.4.2. + +#### 12.4.5.5 Output data + +A list (represented as a JSON array) of JSON-LD objects each one representing +subscription details as mandated by Clause+++clause-5+++5.2.6.5.2. + +### 12.4.6 Delete Context Source Registration Subscription + +#### 12.4.6.1 Description + +This operation allows deleting an existing [Context Source +Registration]{.HTML-Keyboard} Subscription. + +#### 12.4.6.2 Use case diagram + +A context source subscriber can delete a [Context Source +Registration]{.HTML-Keyboard} Subscription as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Context Source Registration Subscriptions use case +::: + + + +#### 12.4.6.3 Input data + +- A subscription identifier (URI). + +#### 12.4.6.4 Behaviour + +- If the subscription Id is not present or it is not a valid URI, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- If the subscription id provided does not correspond to any existing + subscription in the system then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- Otherwise implementations shall delete the [Context Source + Registration]{.HTML-Keyboard} Subscription and no longer perform notifications + concerning that Subscription. + +#### 12.4.6.5 Output data + +None. + +### 12.4.7 Notification behaviour + +A [Context Source]{.HTML-Keyboard} Notification is a message that allows a +subscriber to be aware of the changes in the set of [Context Source +Registrations]{.HTML-Keyboard} describing [Context Sources]{.HTML-Keyboard} that +can potentially provide the requested context information. Implementations shall +exhibit the behaviour described in Clause+++clause-10+++10.5.7 with the +following exceptions: + +- If a subscription defines a _`timeInterval`_ member, a _CsourceNotification_ + (Clause+++clause-5+++5.2.6.9.4) shall be sent on initial subscription and + periodically, when the time specified time interval (in seconds) has elapsed, + regardless of any changes to the set of context source registrations. The + _CsourceNotification_ message shall include all the [Context Source + Registrations]{.HTML-Keyboard} whose _`information`_ property matches the + entities and watched Attributes or Attributes specified in the notification + parameter and, if present, have a matching geoquery. If either the watched + Attributes or the Attributes in the notification are not present or of length + 0, all possible Attributes (if present in the [Context Source + Registrations]{.HTML-Keyboard}) for fitting entities match. +- If a subscription does not define a _`timeInterval`_ term, the csource + notification shall be sent on initial subscription and whenever there is a + change in a matching csource registration. Such a change may be triggered by + the creation of a new matching csource registration, the update of a csource + registration (whether matching before the update, after the update or in both + cases) or the deletion of a matching csource registration. The notification + message shall include the matching csource registration(s) together with the + appropriate trigger reason in the _`triggerReason`_ member. +- Instead of providing the original [Context Source + Registration]{.HTML-Keyboard} which may contain a lot of irrelevant + information, implementations should return filtered [Context Source + Registrations]{.HTML-Keyboard}, which only contain context source registration + information relevant for the subscription, in particular only matching + _RegistrationInfo_ elements. +- A csource notification shall be sent as follows: + - The structure of the csource notification message shall be as mandated by + Clause+++clause-5+++5.2.6.9.4. + - A csource notification shall be sent to the _`endpoint`_. + - The _`notification.timesSent`_ member shall be incremented by one. + - The _`notification.lastNotification`_ member shall be updated with the + current timestamp. + - If the notification is sent successfully: + - Update _`notification.lastSuccess`_ with the current timestamp. + + - If the notification is not sent successfully: + - Update _`notification.lastFailure`_ with the current timestamp. + - Update the subscription _`status`_ to ["failed"]{.HTML-Code}. diff --git a/md/clause-13.md b/md/clause-13.md new file mode 100644 index 0000000000000000000000000000000000000000..e32ab5ad106b5ad29ddc6594934606c46775f6a8 --- /dev/null +++ b/md/clause-13.md @@ -0,0 +1,307 @@ +# 13 Storing, managing and serving \@contexts operations + +## 13.1 Introduction + +[Context Brokers]{.HTML-Keyboard} optionally (see clause 6) offer the capability +to store and serve _`@contexts`_ to clients. The stored _`@contexts`_ may be +managed by clients directly, via the APIs specified in clause 13. Clients can +store custom user _`@contexts`_ at the Context Broker, effectively using the +Context Broker as a _`@context`_ server. + +Moreover, in order to optimize performance, brokers may automatically store and +use the stored copies of common _`@contexts`_ as a local cache, downloading them +just once, thus avoiding fetching them over and over again at each NGSI-LD +request. In order for the broker to understand if a needed _`@context`_ is +already in the local storage or not, the broker uses the URL, where the +_`@context`_ is originally hosted, as an identifier for it in the local storage. +Consequently, the broker has no ability to cache _`@contexts`_ that arrive to it +as **embedded** parts within the NGSI-LD documents, since they are not uniquely +(and implicitly) identified by any URL; [Context Brokers]{.HTML-Keyboard} only +cache _`@contexts`_ that are referred to by means of explicit URLs (either in +the HTTP Link header or as URLs in the payload body). Thus, the **recommended +best-practice, in order to exploit caching, is that clients do not embed their +user** _`@contexts`_ **into their NGSI-LD documents**; instead clients should +explicitly host their user _`@contexts`_ at their premises, or use the broker's +capability to host user _`@contexts`_ on their behalf. + +When an external _`@context`_ is stored, either explicitly upon a client's +request or implicitly downloaded for caching purposes, the Context Broker +generates a unique local _`@context`_ identifier. The original _`@context's`_ +URL, if any, is stored alongside the generated local id. The local id is then +used for subsequent managing operations on the specific _`@context`_, that are +specified in ~clauses 13.2 to 13.5. Moreover, the broker tags the entry with the +current timestamp, (_`createdAt`_) so that, subsequently, clients can check the +timestamp before deciding whether to force a refresh of the stored copy of the +_`@context`_. This is primarily intended as a means for clients to well-behave, +thus avoiding triggering continuous refresh of a stored _`@context`_ on the +broker, for fear that it is not at the latest version. + +Stored _`@contexts`_ are flagged as one of three kinds: ["Cached"]{.HTML-Code}, +["Hosted"]{.HTML-Code}, ["ImplicitlyCreated"]{.HTML-Code}: + +- **Cached:** _`@contexts`_ implicitly and automatically fetched by the broker + from external URLs during normal NGSI-LD operations are flagged as + ["Cached"]{.HTML-Code}. A locally unique identifier is generated for each + _`@context`_ not already in the internal storage. The downloaded content, its + URL and the current time in UTC are stored alongside the locally unique + identifier. Implementations shall periodically invalidate the "Cached" + _`@contexts`_. Depending on the binding of the NGSI-LD API to a specific + protocol, that specific protocol may provide explicit indications about + expiration times of cached content. In such cases, implementations shall + comply with the indications provided by the protocol. Implementations should + assign a heuristic expiration time when an explicit time is not specified. + **Entries flagged as "Cached" shall not be served by brokers on-demand, but + only be used as a local cache to improve performance**. +- **Hosted:** _`@contexts`_ that are explicitly added by users are flagged as + ["Hosted"]{.HTML-Code}. These entries shall be served by brokers on-demand. +- **ImplicitlyCreated:** _`@contexts`_ that are implicitly, but ex-novo, created + by the broker as a result of a user request are flagged as + ["ImplicitlyCreated"]{.HTML-Code}. For instance, when a client creates a + subscription using an _`@context`_ that is an array, and the broker has to + notify with Content-Type ["application/json"]{.HTML-Code}, then the broker + needs this _`@context`_ array to be hosted at a URL. Hence the broker has to + create a new _`@context`_ that is an array, and it is going to be served from + an own URL. These entries shall be served by brokers on-demand. + +## 13.2 Add \@context + +### 13.2.1 Description + +With this operation, a client can ask the broker to store the full content of a +specific _`@context`_, by giving it to the broker. + +### 13.2.2 Use case diagram + +A client can add an _`@context`_ to be stored within an NGSI-LD system as shown +in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Add \@context use case +::: + + + +### 13.2.3 Input data + +A JSON object that has a top-level field named _`@context`_, i.e. a JSON object +representing a JSON-LD "local context". As specified in the JSON-LD +specification [n.8], all extra information located outside of the _`@context`_ +subtree in the referenced object shall be discarded. + +### 13.2.4 Behaviour + +A new entry is created in the local storage and a locally unique identifier +(URI) is generated for it. The JSON object representing the client-supplied +_`@context`_ and the current UTC time are stored alongside the locally unique +identifier. That identifier shall be given back as a result in the output data. +The entry is flagged as being of kind ["Hosted"]{.HTML-Code}. + +The behaviour described in clause 8.2.3 about JSON and JSON-LD validation shall +be applied in case of invalid _`@context`_. + +### 13.2.5 Output data + +A locally unique URI identifying the _`@context`_ in the broker's internal +storage. + +## 13.3 List \@contexts + +### 13.3.1 Description + +With this operation a client can obtain a list of URLs that represent all of the +_`@contexts`_ stored in the local context store of the broker. Each URL can be +used to download the corresponding _`@context`_, and, in case the +[@context's]{.HTML-Variable} kind is ["Cached"]{.HTML-Code}, it shall be the +original URL the broker downloaded the _`@context`_ from. + +In case a [details]{.HTML-Variable} flag is set to [true]{.HTML-Variable}, the +client obtains a list of JSON objects, each representing information (metadata) +about an _`@context`_ currently stored by the broker. Each JSON object contains +information about the [@context's]{.HTML-Variable} original URL (if any), its +local identifier in the broker's storage, its kind (["Cached"]{.HTML-Code}, +["Hosted"]{.HTML-Code} and ["ImplicitlyCreated"]{.HTML-Code}), its creation +timestamp, its expiry date, and additional optional information. + +### 13.3.2 Use case diagram + +A client can list all _`@contexts`_ stored within an NGSI-LD system as shown in +Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: List \@contexts use case +::: + + + +### 13.3.3 Input data + +- A [kind]{.HTML-Variable} filter indicating the kind of stored _`@contexts`_ + that are to be included in the output list. Currently, possible kinds are + ["Cached"]{.HTML-Code}, ["Hosted"]{.HTML-Code} and + ["ImplicitlyCreated"]{.HTML-Code} (optional). +- A boolean [details]{.HTML-Variable} flag indicating that detailed JSON objects + representing metadata about the stored _`@contexts`_ instead of simple URLs + are requested (optional). + +### 13.3.4 Behaviour + +The broker shall provide a URL or JSON object for each _`@context`_ currently +stored in the internal broker's storage, that match the filter. If no filter is +specified, all kinds are included. + +### 13.3.5 Output data + +A list of URLs, or a list of resulting JSON objects containing the following +fields: + +- URL; +- _`localId`_ +- _`kind`_ +- _`createdAt`_ +- _`expiresAt`_ (OPTIONAL); +- _`lastUsage`_ (OPTIONAL); +- _`numberOfHits`_ (OPTIONAL, number of times the _`@context`_ was found in the + storage); +- _`extraInfo`_ (OPTIONAL, used by implementations to report any kind of custom + information). + +## 13.4 Serve \@context + +### 13.4.1 Description + +With this operation a client can obtain the full content of a specific +_`@context`_ (only for _`@contexts`_ of kind ["Hosted"]{.HTML-Code} or +["ImplicitlyCreated"]{.HTML-Code}), which is currently stored in the broker's +internal storage, or its metadata (for all kinds of stored _`@contexts`_). + +### 13.4.2 Use case diagram + +A client can request the broker to serve a specific _`@context`_ stored within +the NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Serve \@context use case +::: + + + +### 13.4.3 Input data + +- The locally unique identifier that identifies the desired _`@context`_ in the + broker's internal storage. Such unique identifiers are obtained by the client + as a result of either a "Add \@context" (clause 13.2) API operation or of a + "List \@contexts" (clause 13.3) API operation. For _`@contexts`_ of kind + ["Cached"]{.HTML-Code} this can also be the original URL the broker downloaded + the _`@context`_ from. +- A boolean [details]{.HTML-Variable} flag indicating that a JSON object + representing metadata about the _`@context`_, instead of the full content, is + requested (optional). + +### 13.4.4 Behaviour + +- If [details]{.HTML-Variable} is set to [false]{.HTML-Variable}, or + [details]{.HTML-Variable} is not present, the broker shall give back the full + content of the _`@context`_ that corresponds to the indicated local + identifier, serving it from its internal storage, if the _`@context`_ that + corresponds to the indicated local identifier is of kind + ["Hosted"]{.HTML-Code} or ["ImplicitlyGenerated"]{.HTML-Code}. It shall give + back [OperationNotSupported]{.HTML-Error} error if it is of kind + ["Cached"]{.HTML-Code}. It shall give back [ResourceNotFound]{.HTML-Error} if + the identifier is not found. +- Otherwise, if [details]{.HTML-Variable} is set to [true]{.HTML-Variable}, the + broker shall give back metadata about the _`@context`_ that corresponds to the + indicated local identifier. It shall give back [ResourceNotFound]{.HTML-Error} + error if the identifier is not found. + +### 13.4.5 Output data + +The full content of the indicated _`@context`_ (or its metadata as specified in +clause 13.3.5), or +[ResourceNotFound]{.HTML-Error}/[OperationNotSupported]{.HTML-Error} errors. + +## 13.5 Delete and reload \@context + +### 13.5.1 Description + +With this operation, a client supplies a local identifier to the broker, +indicating a stored _`@context`_, that the broker shall remove from its storage. +For _`@contexts`_ of kind ["Cached"]{.HTML-Code} this can also be the original +URL the broker downloaded the _`@context`_ from. If the entry in the local +storage that corresponds to the identifier is itself an array of _`@contexts`_, +this operation will **not** delete the children, i.e. the _`@contexts`_ in the +array, but just the entry. + +### 13.5.2 Use case diagram + +A client can request the broker to delete (and optionally reload) a specific +_`@context`_ stored within the NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete and reload \@context use case +::: + + + +### 13.5.3 Input data + +- The locally unique identifier that identifies the desired _`@context`_ in the + broker's internal storage. For _`@contexts`_ of kind ["Cached"]{.HTML-Code} + this can also be the original URL the broker downloaded the _`@context`_ from. +- A [reload]{.HTML-Variable} boolean flag indicating that reloading of the + _`@context`_ shall be attempted (optional). + +### 13.5.4 Behaviour + +- If the _`@context`_ identifier is not supplied, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the _`@context`_ identifier does not correspond to any existing entry in + the _`@context`_ storage, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- If [reload]{.HTML-Variable} is [true]{.HTML-Variable} and the kind of the + _`@context`_ is ["Cached"]{.HTML-Code}, implementations shall try to + re-download the identified _`@context`_ from its original URL, before removing + it from the internal storage. If downloading fails, or the downloaded + _`@context`_ is invalid according to JSON and JSON-LD validation of clause + 8.2.3, then an error of type [LdContextNotAvailable]{.HTML-Error} shall be + raised. More detailed information about the errors shall be specified in the + [ProblemDetails]{.HTML-Definition} (see IETF RFC 7807 [n.6]) field of the + response. In case of any error, the operation ends without removing the + existing _`@context`_. Otherwise, the existing _`@context`_ is replaced with + the newly downloaded one. +- If [reload]{.HTML-Variable} is [true]{.HTML-Variable} and the kind of the + _`@context`_ is **not** ["Cached",]{.HTML-Code} implementations shall return a + [BadRequestData]{.HTML-Error} error. +- If [reload]{.HTML-Variable} is [false]{.HTML-Variable} (or + [reload]{.HTML-Variable} is not supplied), implementations shall remove from + the internal storage the _`@context`_ that corresponds to the given + identifier. The local identifier is used for finding the _`@contexts`_ in the + internal broker's storage. If the local identifier is not in the storage, a + [ResourceNotFound]{.HTML-Error} error shall be raised. + +### 13.5.5 Output data + +None. diff --git a/md/clause-14.md b/md/clause-14.md new file mode 100644 index 0000000000000000000000000000000000000000..9438dac9dd1723e854761b83dc1b4ba08456898d --- /dev/null +++ b/md/clause-14.md @@ -0,0 +1,556 @@ +# 14 Context Source Entity mapping operations + +## 14.1 Introduction + +The idea of [Entity Maps]{.HTML-Keyboard} is to have a consistent set of +Entities based on which a request is answered, even if not all Entities can be +returned directly and pagination is needed. When receiving the request, first an +[Entity Map]{.HTML-Keyboard} of ["type": "EntityMap"]{.HTML-Code} is created +that lists all relevant Entities and from where they can be retrieved -- from +the local storage as well as from registered [Context Sources]{.HTML-Keyboard}. +The [Entity Map]{.HTML-Keyboard} then enables pagination through a consistent +result, i.e. the requester can then go forwards and backwards through the pages +with consistent Entities. Clause+++root describes all operations related to +creating and managing [Entity Maps]{.HTML-Keyboard}. + +## 14.2 Retrieve Entity Map + +### 14.2.1 Description + +With this operation a client can obtain a cached [Entity Map]{.HTML-Keyboard} +which is currently stored in the [Context Broker]{.HTML-Keyboard}'s internal +storage, or memory. + +### 14.2.2 Use case diagram + +A client can request the [Context Broker]{.HTML-Keyboard} to retrieve a specific +[Entity Map]{.HTML-Keyboard} within the NGSI-LD system as shown in +Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Entity Map +::: + + + +### 14.2.3 Input data + +[Entity Map]{.HTML-Keyboard} identifier (id) (URI) of the [Entity +Map]{.HTML-Keyboard} to be retrieved (target [Entity Map]{.HTML-Keyboard}). + +### 14.2.4 Behaviour + +- If the [Entity Map]{.HTML-Keyboard} ID is not present or it is not a valid + URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about a matching [Entity + Map]{.HTML-Keyboard} for the [Entity Map]{.HTML-Keyboard} ID, then an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- Otherwise, return a JSON-LD object representing the [Entity + Map]{.HTML-Keyboard} as mandated by Clause+++clause-5+++root.2.6.5.5. + +### 14.2.5 Output data + +A JSON-LD object representing the target [Entity Map]{.HTML-Keyboard} as +mandated by Clause+++clause-5+++root.2.6.5.5. + +## 14.3 Update Entity Map + +### 14.3.1 Description + +This operation allows performing a **partial update on an NGSI-LD EntityMap.** A +partial update only changes the elements provided in the [Entity +Map]{.HTML-Keyboard} Fragment, leaving the rest as they are. + +### 14.3.2 Use case diagram + +A client can request the [Context Broker]{.HTML-Keyboard} to update an [Entity +Map]{.HTML-Keyboard} which is currently stored in the [Context +Broker]{.HTML-Keyboard}'s internal storage as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure 14.3.2-1: Update Entity Map +::: + + + +### 14.3.3 Input data + +- [Entity Map]{.HTML-Keyboard} ID (URI) of the [Entity Map]{.HTML-Keyboard} to + be updated (target [Entity Map]{.HTML-Keyboard}). +- A JSON-LD document representing a fragment of an [Entity Map]{.HTML-Keyboard}. + +### 14.3.4 Behaviour + +- If the [Entity Map]{.HTML-Keyboard} ID is not present or it is not a valid + URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about a matching [Entity + Map]{.HTML-Keyboard} for the [Entity Map]{.HTML-Keyboard} ID, then an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- Perform an update operation on the target [Entity Map]{.HTML-Keyboard} using + the fields specified within then JSON-LD document. Any provided output-only + fields shall be ignored. + +### 14.3.5 Output data + +None. + +## 14.4 Delete Entity Map + +### 14.4.1 Description + +This operation allows deleting an [Entity Map]{.HTML-Keyboard}. + +### 14.4.2 Use case diagram + +A client can request the [Context Broker]{.HTML-Keyboard} to completely delete +an [Entity Map]{.HTML-Keyboard} held within the NGSI-LD system as shown in +Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Entity Map +::: + + + +### 14.4.3 Input data + +[Entity Map]{.HTML-Keyboard} ID (URI) of the [Entity Map]{.HTML-Keyboard} to be +retrieved (target [Entity Map]{.HTML-Keyboard}). + +### 14.4.4 Behaviour + +- If the [Entity Map]{.HTML-Keyboard} ID is not present or it is not a valid + URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint does not know about a matching [Entity + Map]{.HTML-Keyboard} for the [Entity Map]{.HTML-Keyboard} ID, then an error of + type [ResourceNotFound]{.HTML-Error} shall be raised. +- The [Entity Map]{.HTML-Keyboard} shall be removed from the [Context + Broker's]{.HTML-Keyboard} internal storage, or memory. + +### 14.4.5 Output data + +None. + +## 14.5 Create Entity Map for query Entities + +### 14.5.1 Description + +This operation is very similar to the Query Entities operation in +Clause+++clause-10+++root.4.3, except that it does not directly return Entities, +but creates and returns an [Entity Map]{.HTML-Keyboard} of ["type": +"EntityMap"]{.HTML-Code}, including the identifiers of the Entities that are +candidates to be part of the query results. The [Entity Map]{.HTML-Keyboard} can +then be used for paginating through the included Entities. + +### 14.5.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve an [Entity +Map]{.HTML-Keyboard} with the Entities that match a specific query from an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure 14.5.2-1: Query Entities for creating EntityMap use case +::: + + + +### 14.5.3 Input data + +To simplify the operation, the same parameters as for the Query Entities +operation (Clause+++clause-10+++root.4.3) are allowed, but some of these are +irrelevant for creating an [Entity Map]{.HTML-Definition} and thus shall be +ignored. + +- A reference to a JSON-LD _`@context`_ (optional). +- A selector of Entity types as specified by Clause+++clause-7+++root.2.2 + (optional). Both type names (short hand string) and fully qualified type names + (URI) are allowed in the selector. +- A list (one or more) of Entity identifiers (optional). +- A list (one or more) of Attribute names of which at least one shall exist in + order for an Entity to be selected, and also used as query projection + attributes (as described by Clause+++clause-7+++root.3.3) (optional). +- A restrictive list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + retrieved (projection attributes as defined by Clause+++clause-7+++root.3.2) + (optional). +- An exclusionary list member names (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, + ["scope"]{.HTML-Code} or an Attribute name) to be removed (projection + attributes as defined by Clause+++clause-7+++root.3.2) (optional). +- An id pattern as a regular expression (optional). +- An NGSI-LD query (to filter out Entities by Attribute values) as per + Clause+++clause-7+++root.2.3 (optional). +- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as + mandated by Clause+++clause-7+++root.2.4 (optional). +- In the case of GeoJSON representation: + - The name of the [GeoProperty]{.HTML-Definition} attribute to use as the + geometry for the GeoJSON representation as mandated by + Clause+++clause-5+++root.3.3 (**ignored**). + - A _`datasetId`_ specifying which instance of the value is to be selected if + the GeoProperty value has multiple instances as defined by + Clause+++clause-8+++root.5 (**ignored**). +- A NGSI-LD Scope query (to filter out Entities based on their Scope) as + mandated by Clause+++clause-7+++root.2.5 (optional). +- An NGSI-LD query (called context source filter, to filter out [Context + Sources]{.HTML-Keyboard} by the values of properties that describe them) as + per Clause+++clause-7+++root.2.3 (optional). +- A limit to the number of Entities to be retrieved. See + Clause+++clause-7+++root.4.2 (**ignored**). +- A specified language filter as per Clause+++clause-7+++root.2.7 (optional). +- A list (one or more) of Attribute names whose values shall be expanded to URIs + prior to executing a query (optional). +- An optional flag indicating whether to include additional [Linked + Entities]{.HTML-Keyboard} corresponding to the + [Relationships]{.HTML-Definition} retrieved and how to format those [Linked + Entities]{.HTML-Keyboard}. See Clause+++clause-7+++root.7 (optional). +- A limit to the depth of [Linked Entities]{.HTML-Keyboard} to search whilst + traversing an Entity Graph. See Clause+++clause-7+++root.7 (optional). +- A list (one or more) of [Linked Entity identifiers]{.HTML-Keyboard} previously + encountered whilst traversing an Entity Graph. See Clause+++clause-7+++root.7 + (optional). +- A flag indicating whether to return the location of the [Entity + Map]{.HTML-Keyboard} used within the operation (**ignored**, [Entity + Map]{.HTML-Keyboard} is always returned). +- A suggested expiry time for the [Entity Map]{.HTML-Keyboard} (optional). +- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching + Entity registrations (**ignored**). +- A _`datasetId`_ parameter that specifies which Attribute instances are to be + selected as defined by Clause+++clause-8+++root.5 (optional). +- A flag indicating whether split Entities are to be expected, i.e. Entities + whose information is distributed across different [Context + Sources]{.HTML-Keyboard} (optional). + +In the general case, it is not possible to retrieve a set of Entities by only +specifying desired Entity identifiers, without further specifying restrictions +on the Entities' types or attributes, either explicitly, via selector of Entity +types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. +If the execution of the operation is limited to the local scope (see +Clause+++clause-8+++root.6), no further restrictions have to be provided. + +### 14.5.4 Behaviour + +- At least one of the following input data shall be provided: + + + + a. selector of Entity Types; + b. list of Attribute names, including at least one non-system Attribute; + c. NGSI-LD Query, including at least one non-system Attribute; + d. NGSI-LD GeoQuery; + e. local scope (see Clause+++clause-8+++root.6). + + If none of the above is provided, then an error of type [BadRequestData]{.HTML-Error} + + + +- If the list of Entity identifiers includes a URI which it is not valid, or the + query, geoquery or context source filter are not syntactically valid (as per + the referred Clause+++clause-7+++root.2.3 and Clause+++clause-7+++root.2.4) an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If projection attributes are present and indicate the use of [Linked + Entity]{.HTML-Keyboard} retrieval, and the use of [Linked + Entity]{.HTML-Keyboard} retrieval is not specified, or the projected attribute + depth exceeds the [Linked Entity]{.HTML-Keyboard} retrieval depth, then an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the filter conditions specified by the query includes [Linked + Entity]{.HTML-Keyboard} attributes, and the use of [Linked + Entity]{.HTML-Keyboard} retrieval is not specified, or the [Linked + Entity]{.HTML-Keyboard} attribute query depth exceeds the [Linked + Entity]{.HTML-Keyboard} retrieval depth, an error of type + [BadRequestData]{.HTML-Error} shall be raised (too deep query). +- If geometryProperty parameter is present and the Accept Header is not set to + ["application/geo+json"]{.HTML-Code}, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- Otherwise, + - Term to URI expansion of type and Attribute names shall be performed, as + mandated by Clause+++clause-8+++root.2.4. + - If a list of Attribute names whose values shall be expanded to URIs has been + supplied, JSON-LD type coercion shall be performed as mandated by + Clause+++clause-8+++root.2.4. + - If split entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split entities, and local scope + is not specified, implementations shall run a query that shall return an + [Entity Map]{.HTML-Keyboard} containing the identifiers of all the Entities + found locally that meet all of the following conditions: + - id is equal to any of the id(s) passed as a parameter; + - the Entity Type names match the selector of Entity Types (expanded) that + is passed as a parameter; + - id matches the id pattern passed as a parameter. + - Otherwise, implementations shall run a query that shall return an [Entity + Map]{.HTML-Keyboard} containing the identifiers pf all Entities found + locally that meet all of the following conditions (given the respective + parameter is provided): + - id is equal to any of the id(s) passed as a parameter; + - the Entity Type names match the selector of Entity Types (expanded) that + is passed as a parameter; + - Attribute matches any of the expanded attribute(s) in the list that is + passed as a parameter; + - id matches the id pattern passed as a parameter; + - the filter conditions specified by the query are met (as mandated by + Clause+++clause-7+++root.2.3); + - the geospatial restrictions imposed by the geoquery are met (as mandated + by Clause+++clause-7+++root.2.4); if there are multiple instances of the + GeoProperty on which the geoquery is based, it is sufficient if any of + these instances meets the geospatial restrictions; + - if the Scope query is present, it shall match a present Entity Scope (as + mandated by Clause+++clause-7+++root.2.5, for an example see [i.16] ~annex + A.16); + - if the Attribute list is present, in order for an Entity to match, it + shall contain at least one of the Attributes in the projection Attribute + list. +- Unless local scope is specified (see Clause+++clause-8+++root.6), for [Context + Source Registrations]{.HTML-Keyboard} that match the query and support the + "createEntityMapQueryEntity" operation (see operations and operation groups in + Clause+++clause-9+++root.2), implementations shall do the following: + - If split entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split entities, the filters + (filter conditions specified by the query, geospatial restrictions imposed + by the geoquery, Scope query, Attributes) shall be removed before forwarding + the request. + - For each matching [Context Source Registration]{.HTML-Keyboard}, the request + is forwarded for remote querying by matching endpoints. The result of each + remote query is an [Entity Map]{.HTML-Keyboard}. The mapping between the + Context Source Registration and the [Entity Map]{.HTML-Keyboard} Id is added + to the _`linkedMaps`_ element of the local [Entity Map]{.HTML-Keyboard} and + for the Entity ids included in the returned [Entity Maps]{.HTML-Keyboard} a + mapping to the Context Source Registration is added to the _`entityMap`_ + element of the local [Entity Map]{.HTML-Keyboard}. +- The local [Entity Map]{.HTML-Keyboard} is stored and made accessible based on + its identifier. + +### 14.5.5 Output data + +The location of the local [Entity Map]{.HTML-Keyboard} shall be returned in a +specific field in the response, as well as the [Entity Map]{.HTML-Keyboard} +itself. + +## 14.6 Create Entity Map for query Temporal Evolution of Entities + +### 14.6.1 Description + +This operation is very similar to the Query Temporal Evolution of Entities +operation in Clause+++clause-11+++root.3.3, except that it does not directly +return the [Temporal Evolution of Entities]{.HTML-Keyboard} but creates and +returns an [Entity Map]{.HTML-Keyboard} including the identifiers of the +Entities that are candidates to be part of the query results. The [Entity +Map]{.HTML-Keyboard} can then be used for paginating through Temporal Evolution +of the included Entities. + +### 14.6.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve an [Entity +Map]{.HTML-Definition} with the Temporal Evolution of a set of Entities which +matches a specific query from an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure 14.6.2-1: Query Temporal Evolution for creating EntityMap use case +::: + + + +### 14.6.3 Input data + +To simplify the operation, the same parameters as for the Query Temporal +Evolution of Entities operation (Clause+++clause-11+++root.3.3) are allowed, but +some of these are irrelevant for creating an [Entity Map]{.HTML-Definition} and +thus will be ignored. + +- An NGSI-LD temporal query as mandated by Clause+++clause-7+++root.2.6. +- A reference to a JSON-LD _`@context`_ (optional). +- A selector of Entity types as specified by Clause+++clause-7+++root.2.2 + (optional). Both type name (short hand string) and fully qualified type name + (URI) are allowed. +- A restrictive list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + retrieved (projection attributes as defined by Clause+++clause-7+++root.3.2) + (optional). +- An exclusionary list of Entity member names (["id"]{.HTML-Code}, + ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) to be + removed (projection attributes as defined by Clause+++clause-7+++root.3.2) + (optional). +- A list (one or more) of Entity identifiers (optional). +- A list (one or more) of Attribute names of which at least one shall exist in + order for an Entity to be selected, and also used as query projection + attributes (as described by Clause+++clause-7+++root.3.3) (optional). +- An id pattern as a regular expression (optional). +- An NGSI-LD query (to filter out Entities by Attribute values) as per + Clause+++clause-7+++root.2.3 (optional). +- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as + mandated by Clause+++clause-7+++root.2.4 (optional). +- A NGSI-LD Scope query (to filter out Entities based on their Scope) as + mandated by Clause+++clause-7+++root.2.5 (optional). +- An NGSI-LD query (called context source filter, to filter out [Context + Sources]{.HTML-Keyboard} by the values of properties that describe them) as + per Clause+++clause-7+++root.2.3 (optional). +- A limit to the number of Entities to be retrieved. See + Clause+++clause-7+++root.4.2 (**ignored**). +- A parameter (lastN) conveying that only the last N instances (per Attribute) + within the concerned temporal interval shall be retrieved (optional). +- A specified language filter as per Clause+++clause-7+++root.2.7 (optional). +- A list (one or more) of Attribute names whose values shall be expanded to URIs + prior to executing a query (optional). +- A flag indicating whether to return the location of the [Entity + Map]{.HTML-Keyboard} used within the operation (**ignored**, [Entity + Map]{.HTML-Keyboard} is always returned). +- A suggested expiry time for the [Entity Map]{.HTML-Keyboard} (optional). +- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching + Entity registrations (**ignored**). +- A datasetId parameter that specifies which Attribute instances are to be + selected as defined by Clause+++clause-8+++root.5 (optional). +- A flag indicating whether split Entities are to be expected, i.e. Entities + whose information is distributed across different [Context + Sources]{.HTML-Keyboard} (optional). + +In the general case, it is not possible to retrieve a set of entities by only +specifying desired Entity identifiers, without further specifying restrictions +on the entities' types or attributes, either explicitly, via selector of Entity +types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. +If the execution of the operation is limited to the local scope (see +Clause+++clause-8+++root.6), no further restrictions have to be provided. + +### 14.6.4 Behaviour + +- If a temporal query is not provided then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- At least one of the following input data shall be provided: + + + + a. selector of Entity Types; + b. list of Attribute names, including at least one non-system Attribute; + c. NGSI-LD Query, including at least one non-system Attribute; + d. NGSI-LD GeoQuery; + e. local scope (see Clause+++clause-8+++root.6). If none of the above is + provided, then an error of type [BadRequestData]{.HTML-Error}. + + + +- If projection attributes or filter conditions indicate the use of [Linked + Entity]{.HTML-Keyboard} retrieval, an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the list of Entity identifiers includes a URI which it is not valid, or the + query, geoquery or context source filter are not syntactically valid (as per + the referred Clause+++clause-7+++root.2.3 and Clause+++clause-7+++root.2.4) an + error of type [BadRequestData]{.HTML-Error} shall be raised. +- Term to URI expansion of type and Attribute names shall be observed mandated + by Clause+++clause-8+++root.2.4. +- If a list of Attribute names whose values shall be expanded to URIs has been + supplied, JSON-LD type coercion shall be performed as mandated by + Clause+++clause-8+++root.2.4. +- The lastN parameter refers to a number, n, of Attribute instances which shall + correspond to the last n timestamps (in descending ordering) of the temporal + property (by default _`observedAt`_) within the concerned temporal interval. +- Otherwise, + - Let S be the set of selected Entities i.e. the query result set. + - If the split entities flag is explicitly set to true or, if not explicitly + set, the default setting of the deployment allows split entities, and local + scope is not specified, implementations shall run a query so that the result + set contains all the Entities found locally, that meet **all** of the + following conditions (given the respective parameter is provided): + - If id(s) is provided, keep in S only those Entities whose id is equivalent + to any of the id(s) passed as a parameter. + - If an id pattern is provided, keep in S only those Entities whose id + matches the id pattern. + - If a selector of Entity Types is provided, keep in S only those Entities + whose Entity Type names match the selector of Entity Types. + - From S, select only those Entities any of whose Attribute instances + (corresponding to the Attributes specified by the query or all if none are + specified) match the temporal restrictions imposed by the temporal query + (as mandated by Clause+++clause-7+++root.2.6); i.e. if the time series, + for all the concerned Attributes of an Entity, does not include data + corresponding to the temporal query interval, then such Entity shall be + removed from S, thus it shall not appear in the final result set. Let S4 + be this new subset. + - Implementations shall run a query that shall return the set of matching + Entities (all Entities stored locally, in case only a local scope is + specified); the logical steps to select the final result set of Entities, + and the Attribute instances included as part of their temporal + representation, are enumerated as follows: + - If id(s) is provided, keep in S only those Entities whose id is equivalent + to any of the id(s) passed as a parameter. + - If an id pattern is provided, keep in S only those Entities whose id + matches the id pattern. + - If a selector of Entity Types is provided, keep in S only those Entities + whose Entity Type names match the selector of Entity Types. + - From S, select only those Entities any of whose Attribute instances + (corresponding to the Attributes specified by the query or all if none are + specified) match the temporal restrictions imposed by the temporal query + (as mandated by Clause+++clause-7+++root.2.6); i.e. if the time series, + for all the concerned Attributes of an Entity, does not include data + corresponding to the temporal query interval, then such Entity shall be + removed from S, thus it shall not appear in the final result set. Let S1 + be this new subset. + - If a values filter query is provided, from S1, select those Entities whose + Attribute instances (during the interval defined by the temporal query) meet + the matching conditions specified by the query (as mandated by + Clause+++clause-7+++root.2.3); i.e. the values filter query shall be checked + against all the Attribute instances resulting from the initial filtering + performed by the temporal query. Let S2 be this new subset. + - If no values filter query is provided, then S2 is equal to S1. + - If geoquery is present, from S2, select those Entities whose _GeoProperty_ + instances meet the geospatial restrictions imposed by the geoquery (as + mandated by Clause+++clause-7+++root.2.4); those geospatial restrictions + shall be checked against the _GeoProperty_ instances that are within the + interval defined by the temporal query. Let S3 be this new subset. + - If no geoquery is provided, then S3 is equal to S2. + - If the Scope query is present, from S3, select those Entities whose Entity + Scope instances match the Scope query (as mandated by + Clause+++clause-7+++root.2.5, for an example see [i.16] ~annex A.16). Let S4 + be the new subset. + - If no Scope query is provided, then S4 is equal to S3. + - The local [Entity Map]{.HTML-Keyboard} is created based on S4. +- Unless local scope is specified (see Clause+++clause-8+++root.6), for [Context + Source Registrations]{.HTML-Keyboard} that match the query and support the + "createEntityMapQueryTemporal" operation (see operations and operation groups + in Clause+++clause-9+++root.2), implementations shall do the following: + - If split entities flag is explicitly set to true or, if not explicitly set, + the default setting of the deployment allows split entities, the filters + (filter conditions specified by the query, geospatial restrictions imposed + by the geoquery, Scope query, Attributes) shall be removed before forwarding + the request. + - For each matching [Context Source Registration]{.HTML-Keyboard}, the request + is forwarded for remote querying by matching endpoints. The result of each + remote query is an [Entity Map]{.HTML-Keyboard}. The mapping between the + [Context Source Registration]{.HTML-Keyboard} and the [Entity + Map]{.HTML-Keyboard} Id is added to the _`linkedMaps`_ element of the local + [Entity Map]{.HTML-Keyboard} and for the Entity ids included in the returned + Entity Maps a mapping to the [Context Source Registration]{.HTML-Keyboard} + is added to the _`entityMap`_ element of the local [Entity + Map]{.HTML-Keyboard}. +- The local [Entity Map]{.HTML-Keyboard} is stored and made accessible based on + its identifier. + +### 14.6.5 Output Data + +The location of the local [Entity Map]{.HTML-Keyboard} shall be returned in a +specific field in the response, as well as the [Entity Map]{.HTML-Keyboard} +itself. diff --git a/md/clause-15.md b/md/clause-15.md new file mode 100644 index 0000000000000000000000000000000000000000..3da4a81b7334dcfb9b92fb1f22c0ad9cc5a36b41 --- /dev/null +++ b/md/clause-15.md @@ -0,0 +1,54 @@ +# 15 Context Source identity information operations + +## 15.1 Introduction + +Clause+++root describes all operations related to the [Context +Source]{.HTML-Keyboard} identity information API. It allows for retrieving +identity information about [Context Sources]{.HTML-Keyboard}. + +## 15.2 Retrieve Context Source identity information + +### 15.2.1 Description + +With this operation, a client can obtain [Context Source]{.HTML-Keyboard} +identity information which uniquely defines the [Context Source]{.HTML-Keyboard} +itself. In the multi-tenancy use case (see Clause+++clause-7+++7.8), a client +can obtain identify information about a specific [Tenant]{.HTML-Keyboard} within +a [Context Source]{.HTML-Keyboard}. + +### 15.2.2 Use case diagram + +A client can request the broker to retrieve identity information about a +specific [Context Source]{.HTML-Keyboard} within the NGSI-LD system as shown in +Figure++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Context Source Identity Information +::: + + + +### 15.2.3 Input data + +None. + +### 15.2.4 Behaviour + +- If the [Context Source]{.HTML-Keyboard} is unable to supply identity + information about itself, then error of type [NotImplemented]{.HTML-Error} + shall be raised. +- Return a JSON-LD object representing the identity of the [Context + Source]{.HTML-Keyboard} itself as mandated by Clause+++clause-5+++5.2.6.5.6. + This can also include additional configurational data dependent on the + specific [Context Source]{.HTML-Keyboard} implementation. + +### 15.2.5 Output data + +A JSON-LD object representing the identity of the [Context +Source]{.HTML-Keyboard} as mandated by Clause+++clause-5+++5.2.6.5.6. diff --git a/md/clause-16.md b/md/clause-16.md new file mode 100644 index 0000000000000000000000000000000000000000..daff9aee676e8ef979e395c04863b7585b35b750 --- /dev/null +++ b/md/clause-16.md @@ -0,0 +1,351 @@ +# 16 Snapshot functionality operations + +## 16.1 Introduction + +Clause+++root describes all operations related to snapshots. Snapshots allow +creating a consistent (within the limits of the possibly distributed NGSI-LD +system) view of the Entities selected by the queries. It allows consuming these +Entities, but also using provision operations for making available predicted and +simulated information, e.g. as needed for digital twins. Implementing the +[Snapshot API]{.HTML-Keyboard} is optional for NGSI-LD systems. + +## 16.2 Create Snapshot + +### 16.2.1 Description + +This operation allows creating a new snapshot. + +### 16.2.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can create a new snapshot to have a more +consistent basis for queries on the persisted Entity information as shown in +Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Create Snapshot use case +::: + + + +### 16.2.3 Input data + +- A JSON-LD document conforming to the Snapshot data type as mandated by + clause+++clause-5+++root.2.6.5.4. + +### 16.2.4 Behaviour + +- If the data types, cardinalities and restrictions expressed by + Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD endpoint already knows about this Snapshot, as there is an + existing Snapshot whose id (URI) is equivalent, an error of type + [AlreadyExists]{.HTML-Error} shall be raised. +- If the Snapshot document does not include a Snapshot identifier, a new locally + unique identifier (URI) shall be automatically generated by the + implementation. +- The _`createdAt`_ and _`modifiedAt`_ timestamps are set to the current time of + the NGSI-LD system. +- The _`snapshotStatus`_ member is set to _`preparation`_. +- The _`expiresAt`_ member shall be set, taking into account the + _`snapshotLifetime`_ requested, but applying the configured limit of the + NGSI-LD system. +- If the Snapshot document does not include a _`snapshotPriority`_, the + _`snapshotPriority`_ shall be set to 5. +- The request returns, confirming the creation of the snapshot to the requesting + [Context Consumer]{.HTML-Keyboard}, providing the Snapshot identifier. The + status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in + Clause+++root.4. The following is executed in the background. +- Implementations shall execute the Queries specified in the _`snapshotQueries`_ + member, in each case following the behaviour described in + Clause+++clause-10+++root.4.3.4. If the size of the respective results require + pagination, all pages are to be retrieved completely. The response details for + each query execution (aggregated across paginated ones) shall be stored in the + _`snapshotQueryDetails`_ list, at the same position as the query in + _`snapshotQueries`_. +- Implementations shall execute the Temporal Queries specified in the + _`snapshotTemporalQueries`_ member, in each case following the behaviour + described in Clause+++clause-11+++root.3.3.4. If the size of the respective + results require pagination, all pages are to be retrieved completely. The + response details for each query execution (aggregated across paginated ones) + shall be stored in the _`snapshotTemporalQueryDetails`_ list, at the same + position as the query in _`snapshotTemporalQueries`_. +- The retrieved Entity information shall be stored by the NGSI-LD system, so + that local NGSI-LD operations can then be executed on it. +- After all information has been stored, the _`snapshotStatus`_ member is set to + ["success"]{.HTML-Code}, if all queries and temporal queries were executed + successfully and yielded at least one result, to ["partial"]{.HTML-Code}, if + at least one query or temporal query was executed successfully and yielded a + result, to ["empty"]{.HTML-Code}, if at least one query or temporal query was + executed successfully, but without yielding a result, and to + ["failure"]{.HTML-Code} otherwise. +- If the _`endpoint`_ member is present, a Snapshot notification is sent as + described in Clause+++root.8. + +### 16.2.5 Output data + +A URI identifying the newly created Snapshot. + +## 16.3 Clone Snapshot + +### 16.3.1 Description + +This operation allows cloning a snapshot stored in an NGSI-LD system. + +### 16.3.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can clone an existing snapshot stored in an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Clone Snapshot use case +::: + + + +### 16.3.3 Input data + +- A URI identifying the Snapshot to be cloned. +- A JSON-LD document conforming to the Snapshot data type as mandated by + Clause+++clause-5+++root.2.6.5.4, but without _`snapshotQueriesDetails`_ and + _`snapshotQueriesTemporalDetails`_ elements. + +### 16.3.4 Behaviour + +- If the data types, cardinalities and restrictions expressed by + Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- If the identifier of the Snapshot to be cloned is not found, an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- If the Snapshot document includes a Snapshot identifier and there is an + existing Snapshot whose id (URI) is equivalent, an error of type + [AlreadyExists]{.HTML-Error} shall be raised. +- If the Snapshot document does not include a Snapshot identifier, a new locally + unique identifier (URI) shall be automatically generated by the + implementation. +- The _`createdAt`_ and _`modifiedAt`_ timestamps of the clone are set to the + current time of the NGSI-LD system. +- The _`snapshotStatus`_ member of the clone is set to _`preparation`_. +- The _`expiresAt`_ member shall be set, taking into account the + _`snapshotLifetime`_ requested, but applying the configured limit of the + NGSI-LD system. +- The request returns, confirming the creation of the cloned Snapshot to the + requesting [Context Consumer]{.HTML-Keyboard}. The status is accessible to the + [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The + following is executed in the background. +- All Entity and Temporal Evolution of Entity data that is part of the Snapshot + to be cloned is copied to the clone Snapshot. +- After all information has been stored, the _`snapshotStatus`_ member is set to + ["success"]{.HTML-Code}, if cloning was successful, and to + ["failure"]{.HTML-Code} otherwise. +- If the _`endpoint`_ member is present, a Snapshot notification is sent as + described in Clause+++root.8. + +### 16.3.5 Output data + +A URI identifying the newly created Snapshot. + +## 16.4 Retrieve Snapshot status + +### 16.4.1 Description + +This operation allows retrieving the status of a Snapshot stored in an NGSI-LD +system. + +### 16.4.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can retrieve the status of a Snapshot from +an NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Snapshot Status use case +::: + + + +### 16.4.3 Input data + +Snapshot Id (URI) of the Snapshot whose status is to be retrieved. + +### 16.4.4 Behaviour + +- If the Snapshot Id is not present or it is not a valid URI, then an error of + type [BadRequestData]{.HTML-Error} shall be raised. +- If the identifier provided does not correspond to any existing Snapshot in the + system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. +- Otherwise, implementations shall retrieve the Snapshot status and return it to + the caller. + +### 16.4.5 Output data + +A JSON-LD object representing the Snapshot status as mandated by +Clause+++clause-5+++root.2.6.5.4. + +## 16.5 Update Snapshot status + +### 16.5.1 Description + +This operation allows updating an existing Snapshot. + +### 16.5.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can update an existing Snapshot within an +NGSI-LD system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Update Snapshot Status use case +::: + + + +### 16.5.3 Input data + +- Snapshot Id (URI), the target Snapshot. +- A JSON-LD document representing a Snapshot Fragment + +### 16.5.4 Behaviour + +- If the Snapshot Id is not present or it is not a valid URI, then an error of + type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD System does not know about the target Snapshot, because there + is no existing Snapshot whose id (URI) is equivalent, an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- Execute the behaviour defined in Clause+++clause-8+++root.2.3 on JSON-LD + validation. +- If the data types and restrictions expressed by + Clause+++clause-5+++root.2.6.5.4 are not met by the _Snapshot Fragment_ - in + particular whether elements can be updated - then an error of type + [BadRequestData]{.HTML-Error} shall be raised. +- Term to URI expansion of Attribute names shall be observed as mandated by + Clause+++clause-8+++root.2.4. +- Then, implementations shall modify the target Snapshot as mandated by + Clause+++clause-8+++root.4.2. + +### 16.5.5 Output data + +A JSON-LD object representing the Snapshot status as mandated by +Clause+++clause-5+++root.2.6.5.4. + +## 16.6 Delete Snapshot + +### 16.6.1 Description + +This operation allows deleting an existing Snapshot. + +### 16.6.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can delete a Snapshot within an NGSI-LD +system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Delete Snapshot use case +::: + + + +### 16.6.3 Input data + +- A Snapshot identifier (URI), the target Snapshot. + +### 16.6.4 Behaviour + +- If the Snapshot Id is not present or it is not a valid URI, then an error of + type [BadRequestData]{.HTML-Error} shall be raised. +- If the Snapshot id provided does not correspond to any existing Snapshot in + the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be + raised. +- Otherwise implementations shall delete the Snapshot. + +### 16.6.5 Output data + +None. + +## 16.7 Purge Snapshots + +### 16.7.1 Description + +This operation allows purging selected Snapshots. + +### 16.7.2 Use case diagram + +A [Context Consumer]{.HTML-Keyboard} can purge Snapshots within an NGSI-LD +system as shown in Figure+++below. + + + +::: FL + +::: + +::: TF +Figure: Purge Snapshots use case +::: + + + +### 16.7.3 Input data + +- An NGSI-LD Query to select fitting Snapshots to be purged based on members of + the Snapshot data type (see table 5.2.6.5.4-1), as per + Clause+++clause-7+++root.2.3. + +### 16.7.4 Behaviour + +- If the NGSI-LD Query is not present or it is not a valid as per + Clause+++clause-7+++root.2.3, restricted to members of the Snapshot data type, + then an error of type [BadRequestData]{.HTML-Error} shall be raised. +- Implementations shall purge the Snapshots fitting the NGSI-LD Query. + +### 16.7.5 Output data + +None. + +## 16.8 Snapshot status notification behaviour + +A Snapshot status notification allows the subscriber, typically the creator of +the Snapshot, to be notified when the Snapshot is ready, or in case of any +problems or updates. Implementations shall exhibit the following behaviour: + +- SnapshotNotification (Clause+++clause-5+++root.2.6.9.3) messages can only be + sent, if the _`endpoint`_ member is set. +- SnapshotNotification messages are sent to the URI specified in the + _`endpoint`_ member of the Snapshot status. +- The information in the _`receiverInfo`_ member of the Snapshot status shall be + added to the SnapshotNotification message in the way required for the binding + protocol. +- Snapshot Status Notifications shall be sent after all the specified Snapshot + queries have been executed, the query results have been integrated and the + Snapshot status has been updated accordingly. +- Snapshot status Notifications shall also be sent after any Snapshot status + update, e.g. informing about the actual updated _`expiresAt`_ timestamp. +- The SnapshotNotification shall be as mandated by + Clause+++clause-5+++root.2.6.9.3. diff --git a/md/clause-1_Scope.md b/md/clause-1_Scope.md new file mode 100644 index 0000000000000000000000000000000000000000..88a76b224ac682829fe819d1e18274656a2385e0 --- /dev/null +++ b/md/clause-1_Scope.md @@ -0,0 +1,14 @@ +# 1 Scope + +The present document defines a standardized API for context information +management (NGSI-LD API) enabling close to real-time (right-time) access to +context information/digital twins coming from many different sources (not only +IoT data sources). The present document defines how such an API enables +applications to perform updates on context, register context sources which can +be queried to get updates on context, query information on current and historic +context information and subscribe to receive notifications of context changes. +The criteria for choice of the API characteristics are based on requirements +resulting from the Use Cases ETSI GR CIM 002 [i.4] and other work items ETSI GR +CIM 007 [i.5] (security) and ETSI TS 104 178 [i.6] (information model). The +present document supersedes prior versions, including ETSI CIM 009 [i.7] and +ETSI GS CIM 004 [i.8]. diff --git a/md/clause-2_References.md b/md/clause-2_References.md new file mode 100644 index 0000000000000000000000000000000000000000..1dd98f8ef2843860d9faf8e930e1b2a14afcc9d1 --- /dev/null +++ b/md/clause-2_References.md @@ -0,0 +1,152 @@ +# 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] [IETF RFC 3987](https://www.rfc-editor.org/info/rfc3987): "Internationalized Resource Identifiers (IRIs)". + +[n.2] The Unicode Consortium: "[Unicode® 15.0.0](https://www.unicode.org/versions/Unicode15.0.0/)". + +[n.3] [IETF RFC 8259](https://www.rfc-editor.org/info/rfc8259): "The JavaScript Object Notation (JSON) Data Interchange Format". + +[n.4] [IETF RFC 7946](https://www.rfc-editor.org/info/rfc7946): "The GeoJSON Format". + +[n.5] [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.6] [IETF RFC 7807](https://www.rfc-editor.org/info/rfc7807): "Problem Details for HTTP APIs". + +[n.7] W3C® Recommendation 25 February 2014: "[RDF 1.1 Concepts and Abstract Syntax](https://www.w3.org/TR/rdf11-concepts)". + +[n.8] W3C® Recommendation 16 July 2020: "[JSON-LD 1.1 - A JSON-based Serialization for Linked Data](http://www.w3.org/TR/json-ld/)". + +[n.9] ETSI TS 104 179: "Data Solutions (DATA); NGSI-LD Provenance and Integrity". + +[n.10] [Codes for Units of Measure used in International Trade Revision 9](http://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_Rev9e_2014.xls). + +[n.11] [IETF RFC 5646](https://www.rfc-editor.org/info/rfc5646): "Tags for Identifying Languages". + +[n.12] [IETF RFC 7230](https://www.rfc-editor.org/info/rfc7230): "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing". + +[n.13] [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.14] [IETF RFC 7240](https://www.rfc-editor.org/info/rfc7240): "Prefer Header for HTTP". + +[n.15] [IETF RFC 6067](https://www.rfc-editor.org/info/rfc6067): "BCP 47 Extension U". + +[n.16] [IETF RFC 5234](https://www.rfc-editor.org/info/rfc5234): "Augmented BNF for Syntax Specifications: ABNF". + +[n.17] [IETF RFC 7396](https://www.rfc-editor.org/info/rfc7396): "JSON Merge Patch". + +[n.18] [IETF RFC 3986](https://www.rfc-editor.org/info/rfc3986): "Uniform Resource Identifier (URI): Generic Syntax". + +[n.19] [ECMA-262 Specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/): "ECMAScript® 2022 language specification". + +[n.20] [Unicode® Technical Standard #10](http://unicode.org/reports/tr10/): "Unicode Collation Algorithm". + +[n.21] [Open Geospatial Consortium Inc. OGC 06-103r4](https://portal.opengeospatial.org/files/?artifact_id=25355): "OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture". + +[n.22] [IETF RFC 3282](https://www.rfc-editor.org/info/rfc3282): "Content Language Headers". + +[n.23] [IETF RFC 8141](https://www.rfc-editor.org/info/rfc8141): "Uniform Resource Names (URNs)". +::: + + + +## 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. + + + +Editor Note: Remove [i.1] (referenced it in the Introduction clause) and renumber all the remaining + +::: REFS +[i.1] ETSI ISG CIM: "[NGSI-LD Status](https://docbox.etsi.org/ISG/CIM/Open/NGSI-LD%20Status.pdf)". + +[i.2] [OMA-TS-NGSI_Context_Management-V1_0-20120529-A](http://www.openmobilealliance.org/release/NGSI/V1_0-20120529-A/OMA-TS-NGSI_Context_Management-V1_0-20120529-A.pdf): "NGSI Context Management". + +[i.3] [FIWARE®-NGSI v2 Specification](http://fiware.github.io/specifications/ngsiv2/sle/). + +[i.4] [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.5] [ETSI GR CIM 007](https://www.etsi.org/deliver/etsi_gr/CIM/001_099/007/): "Context Information Management (CIM); Security and Privacy". + +[i.6] ETSI TS 104 178: "Data Solutions (DATA); NGSI-LD Information Model". + +[i.7] [ETSI GS CIM 009 (V1.9.1)](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.09.01_60/gs_cim009v010901p.pdf): "Context Information Management (CIM); NGSI-LD API". + +[i.8] [ETSI GS CIM 004 (V1.1.2)](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/004/01.01.02_60/gs_cim004v010102p.pdf): "Context Information Management (CIM); Application Programming Interface (API)". + +[i.9] Graph Databases: "New Opportunities for Connected Data". O'Reilly 2nd Edition. Webber, Robinson, et al. ISBN:1491930896 9781491930892. + +[i.10] [ETSI TS 103 264 (V4.1.1)](https://www.etsi.org/deliver/etsi_ts/103200_103299/103264/04.01.01_60/ts_103264v040101p.pdf): "SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping". + +[i.11] W3C® Recommendation 25 February 2014: "[RDF Schema 1.1](https://www.w3.org/TR/2014/REC-rdf-schema-20140225/)". + +[i.12] W3C® Recommendation 16 July 2020: "[JSON-LD 1.1 - A JSON-based Serialization for Linked Data](http://www.w3.org/TR/json-ld/)". + +[i.13] [GeoJSON-LD 1.0](http://geojson.org/geojson-ld/). Base context for processing GeoJSON according to the JSON-LD processing model. + +[i.14] [JSON Schema Validation: A Vocabulary for Structural Validation of JSON](https://json-schema.org/draft/2020-12/json-schema-validation.html). + +[i.15] [NGSI-LD JSON Schemas](https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/tree/master/schema). + +[i.16] ETSI TS 104 176: "Data Solutions (DATA); NGSI-LD API Bindings". + +[i.17] [Regulation (EU) 2016/679](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32016R0679) of the European Parliament and of the Council of 27 April 2016 on the protection of natural persons with regard to the processing of personal data and on the free movement of such data, and repealing Directive 95/46/EC (General Data Protection Regulation). + +[i.18] [IETF RFC 6902](https://www.rfc-editor.org/info/rfc6902): "JavaScript Object Notation (JSON) Patch". + +[i.19] [JSON-LD Playground](https://json-ld.org/playground/): "Experimentation tool for JSON-LD". + +[i.20] [NGSI-LD Examples](https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/tree/master/examples). + +[i.21] [NGSI-LD Wrapper](https://github.com/Fiware/NGSI-LD_Wrapper): "Experimental proxy for adaptation between FIWARE® and NGSI-LD". + +[i.22] [IoT Agent Library](https://github.com/telefonicaid/iotagent-node-lib). +::: + + diff --git a/md/clause-3_Definitions.md b/md/clause-3_Definitions.md new file mode 100644 index 0000000000000000000000000000000000000000..aea4705505f3266cb3541b8f20d386dd621cd53c --- /dev/null +++ b/md/clause-3_Definitions.md @@ -0,0 +1,552 @@ +# 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.1], +which extends the use of characters to Unicode characters [n.2] 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..03eb3368a515c8d6e92be57a152c7c8de2c49434 --- /dev/null +++ b/md/clause-4.md @@ -0,0 +1,872 @@ +# 4 NGSI-LD conceptual overview [(informative)]{.inform} + +## 4.1 Introduction + +Clause+++root gives an introduction to the technical design principles behind +the context information management framework supported by NGSI-LD. It provides +an overview of the information model, architectural assumptions and supported +architectures, the respresentation in JSON-LD, and a high-level overview of the +API and its most important features. The clause is informative as it provides an +overview only, leaving out many details. The goal is to put the reader into a +better position to understand the following normative clauses that provide all +the details of the NGSI-LD API. + +As stated in clause 3.1, the letters "NGSI-LD" which are part of most terms, to +confirm that they are distinct from other terms of similar/same name in use in +other organizations, are generally omitted in the present document for brevity. +In the present document, a number of rather obvious typographic conventions and +syntax guidelines are followed, and the reader is referred to annex f for +details. + +## 4.2 NGSI-LD information model + +### 4.2.1 Introduction + +The NGSI-LD Information Model prescribes the structure of context information to +be supported by an NGSI-LD system. It is defined in ETSI TS 104 178 [i.6]. It +specifies the data representation mechanisms to be used by the NGSI-LD API +itself. In addition, it specifies the structure of the Context Information +Management vocabularies to be used in conjunction with the API. + +The NGSI-LD Information Model is defined at two levels (see Figure+++below): the +foundation classes which correspond to the Core Meta-model and the Cross-Domain +Ontology. The former amounts to a formal specification of the "property graph" +model [i.9]. The latter is a set of generic, transversal classes which are aimed +at avoiding conflicting or redundant definitions of the same classes in each of +the domain-specific ontologies. Below these two levels, domain-specific +ontologies or vocabularies can be devised. For instance, the SAREF Ontology ETSI +TS 103 264 [i.10] can be mapped to the NGSI-LD Information Model, so that smart +home applications will benefit from this Context Information Management API +specification. + +The version of the cross-domain model shown in the present document is a minimal +one, aimed at defining the classes used in this release of the API +specification. It has been extended in ETSI TS 104 178 [i.6], with classes +defining extra concepts such as mobile vs. stationary entities, instantaneous +vs. static properties, etc. + +![](media/image2.png) + +**Figure 4.2.1-1: Overview of the NGSI-LD information model structure** + +### 4.2.2 NGSI-LD meta model + +Figure 4.2.2-1 provides a graphical representation of the NGSI-LD Meta-Model in +terms of classes and their relationships. To provide additional clarity an +informal (non-normative) mapping to the property graph model is also presented. + + + +::: FL + +::: + +::: TAL ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Legend: | | +| Model concept | Description | ++============================================================+======================================================================================================================================================================================================================================================================+ +| | [With capital initial]. Used to refer to a class that is a subclass of Entity or Value. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With capital initial]. Used to refer to a class that is a subclass of Property or Relationship, but which is not itself a property or a relationship. These classes serve as super-classes for a set of properties or relationships in the same domain or aspect. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With small initial]. Used to refer to a proper (direct) class of properties or relationships. | +| and | | +| | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With small initial and underlined text]. Used to refer to the name of a property that is considered to be "lite" in its informational representation since it is not be reified, rather a value is directly attached to it. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With small or capital initial]. Used to refer to a class or a vocabulary that is inherited from another publicly available standard or ontology. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + +::: TF +Figure: NGSI-LD core meta-mode +::: + + + +Implementations support the NGSI-LD Meta-model as follows: + +- An **NGSI-LD Entity** is a subclass of rdfs:Resource [i.11]. +- An **NGSI-LD Relationship** is a subclass of rdfs:Resource [i.11]. +- An **NGSI-LD Property** is a subclass of rdfs:Resource [i.11]. +- An **NGSI-LD Value** is either a rdfs:Literal or a node object (in JSON-LD + syntax) to represent complex data structures [i.11]. +- An **NGSI-LD Property** has a **value,** stated through _`hasValue`_, which is + of type rdf:Property [i.11]. +- An **NGSI-LD Relationship** has an **object** stated through _`hasObject`_ + which is of type rdf:Property [i.11]. + +### 4.2.3 Cross-domain ontology + + + +::: FL + +::: + +::: TAL ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Legend: | | +| Model concept | Description | ++============================================================+======================================================================================================================================================================================================================================================================+ +| | [With capital initial]. Used to refer to a class that is a subclass of Entity or Value. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With capital initial]. Used to refer to a class that is a subclass of Property or Relationship, but which is not itself a property or a relationship. These classes serve as super-classes for a set of properties or relationships in the same domain or aspect. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With small initial]. Used to refer to a proper (direct) class of properties or relationships. | +| and | | +| | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With small initial and underlined text]. Used to refer to the name of a property that is considered to be "lite" in its informational representation since it is not be reified, rather a value is directly attached to it. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | [With small or capital initial]. Used to refer to a class or a vocabulary that is inherited from another publicly available standard or ontology. | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + +::: TF +Figure: NGSI-LD core meta-model plus the cross-domain ontology +::: + + + +Figure 4.2.3-1 describes the concepts introduced by the NGSI-LD Cross-Domain +Ontology to be supported by implementations as follows: + +- **Geo Properties:** Are intended to convey geospatial information as defined + in Clause+++clause-5+++root.2.6.4.5. +- **Temporal Properties:** Are non-reified Properties (represented only by their + Value) that convey temporal information for capturing the time series + evolution of other Properties; they are defined in + Clause+++clause-5+++root.2.4. +- **Language Properties:** Are intended to convey different versions of the same + textual values, whenever a version for each language (for instance: English, + Spanish) is needed. +- **"unitCode" Property:** Is a Property intended to provide the units of + measurement of an NGSI-LD Value as defined in + Clause+++clause-5+++root.2.6.4.3. +- **"scope" Property:** Is a Property that enables putting Entities into a + hierarchical structure as defined in Clause+++clause-5+++root.2.7. +- **LanguageMaps:** Are a special type of NGSI-LD Value intended to convey the + different values of Language Properties, stated through an _`hasLanguageMap`_, + which is of type rdf:Property [i.11] and is itself a subproperty of + _`hasValue`_. +- **Geometry Values:** Are a special type of NGSI-LD Value intended to convey + geometries corresponding to geospatial properties as defined in + Clause+++clause-5+++root.2.6.4.5. +- **Time Values:** Are a special type of NGSI-LD Value intended to convey time + instants or intervals representations as defined in + Clause+++clause-5+++root.2.2.4. + +Clause+++clause-4+++root.3.4.3 introduces the Core JSON-LD _`@context`_ which +includes the URIs which correspond to the concepts introduced above. + +### 4.2.4 NGSI-LD domain-specific models and instantiation + +This clause is intended to illustrate the relationship between the NGSI-LD +Information Model and NGSI-LD Domain-specific models. + +Figure+++below shows an example of an NGSI-LD domain-specific model. +Domain-specific models introduce the specific entity types required for a +particular domain. Figure+++below shows the types ["Car"]{.HTML-Code}, +["Parking"]{.HTML-Code}, ["Street"]{.HTML-Code}, ["Gate"]{.HTML-Code}. Entity +types can have further subtypes, e.g. ["OffStreetParking"]{.HTML-Code} as +subtype of ["Parking"]{.HTML-Code}. + + + +::: FL + +::: + +::: TF +Figure: Cross-domain ontology and instantiation +::: + + + +In addition, two different NGSI-LD Properties are introduced (_`hasState`_ and +_`reliability`_). + +The _`adjacentTo`_ Relationship links entities of type ["Parking"]{.HTML-Code} +with entities of type ["Street"]{.HTML-Code}. + +### 4.2.5 UML representation + +This clause is intended to show how the NGSI-LD information model could be +described using UML diagrams. The aim of this diagram is to help those readers +less familiar with ontology representations or RDF [i.11] to understand the +NGSI-LD Information Model. + +In Figure+++below NGSI-LD Entity, Relationship, Property and Value are +represented as UML classes. UML associations are used to interrelate these +classes while keeping the structure and semantics defined by the NGSI-LD +Information Model. + + + +::: FL + +::: + +::: TF +Figure: NGSI-LD information model as UML +::: + + + +## 4.3 NGSI-LD architectures + +### 4.3.1 Introduction + +Originally, the NGSI-LD API has been intended to define an API without +prescribing a specific architecture and thus the NGSI-LD API can be used in +different architectural settings. In the course of time, the distributed +architecture has been described in more details, partially specifying +interactions and behaviours of components in more details to ensure +interoperability between different NGSI-LD systems, partially with +recommendations how to best implement distributed functionality for efficiency +or scalability reasons. + +In the following, the three main architectural setups are described, in which +the NGSI-LD API is being used. Nevertheless, there may be additional +architectural setups in which the NGSI-LD API can also be used. The design +decisions for the NGSI-LD API take the three described architectural setups into +consideration to enable the efficient and scalable operation of NGSI-LD systems. +A real system architecture utilizing the NGSI-LD API can map to one, take +elements from multiple or combine all of them. + +The NGSI-LD API implicitly defines two views of Entities: + +- the "current state"; +- the "temporal evolution" (both the past and possibly future predictions). + +The NGSI-LD API is structured into a [Core API]{.HTML-Keyboard} and an optional +[Temporal API]{.HTML-Keyboard}. The [Core API]{.HTML-Keyboard} manages the +current state of Entities. The [Temporal API]{.HTML-Keyboard} is optional and +manages the [Temporal Evolution of Entities]{.HTML-Keyboard}. NGSI-LD systems +that intend to implement the [Temporal API]{.HTML-Keyboard} can consider +updating the [Temporal Evolution of an Entity]{.HTML-Keyboard} whenever the +"current state" is modified via the [Core API]{.HTML-Keyboard}. + +### 4.3.2 Centralized architecture + +Figure+++below shows a centralized architecture. In the centre is a [Central +Broker]{.HTML-Keyboard} that stores all the context information. There are +[Context Producers]{.HTML-Keyboard} that use update operations to update the +context information in the [Central Broker]{.HTML-Keyboard} and there are +[Context Consumers]{.HTML-Keyboard} that request context information from the +[Central Broker]{.HTML-Keyboard}, either using synchronous one-time query or +asynchronous subscribe/notify operations. The [Central Broker]{.HTML-Keyboard} +answers all requests from its storage. Figure+++below shows one component that +acts as both [Context Producer]{.HTML-Keyboard} and [Context +Consumer]{.HTML-Keyboard}. The general assumption is that components can have +multiple roles, so such components are not explicitly shown in +Clause+++clause-4+++root.3.3. + + + +::: FL + +::: + +::: TF +Figure: Centralized architecture +::: + + + +### 4.3.3 Distributed and federated architectures + +#### 4.3.3.1 Introduction + +Figure+++below shows a distributed architecture. The underlying idea here is +that all information is stored by the [Context Sources]{.HTML-Keyboard}. +[Context Sources]{.HTML-Keyboard} implement the query and subscription part of +the NGSI-LD API as a [Context Broker]{.HTML-Keyboard} does. They register +themselves with the [Context Registry]{.HTML-Keyboard}, providing information +about what context information they can provide, but not the context information +itself, e.g. a certain [Context Source]{.HTML-Keyboard} registers that it can +provide the indoor temperature for Building A and Building B or that it can +provide the speed of cars in a geographic region covering the centre of a city. + + + +::: FL + +::: + +::: TF +Figure: Distributed architecture +::: + + + +[Context Consumers]{.HTML-Keyboard} can query or subscribe to the [Distribution +Broker]{.HTML-Keyboard}. On each request, the [Distribution +Broker]{.HTML-Keyboard} discovers or does a discovery subscription to the +[Context Registry]{.HTML-Keyboard} for relevant [Context +Sources]{.HTML-Keyboard}, i.e. those that may provide context information +relevant to the respective request from the [Context Consumer]{.HTML-Keyboard}. +The [Distribution Broker]{.HTML-Keyboard} then queries or subscribes to each +relevant [Context Source]{.HTML-Keyboard}, if possible it aggregates the context +information retrieved from the [Context Sources]{.HTML-Keyboard} and provides +them to the [Context Consumer]{.HTML-Keyboard}. In this mode of operation, it is +not visible to the [Context Consumer]{.HTML-Keyboard}, whether the [Context +Broker]{.HTML-Keyboard} is a [Central Broker]{.HTML-Keyboard} or a [Distribution +Broker]{.HTML-Keyboard}. Alternatively, the architecture allows that [Context +Consumers]{.HTML-Keyboard} can discover [Context Sources]{.HTML-Keyboard} +through the [Context Registry]{.HTML-Keyboard} themselves and then directly +request from [Context Sources]{.HTML-Keyboard}. This is shown in Figure 4.3.3-1 +with the fine dashed arrows. + +The federated architecture shown in Figure+++below is a variation of the +distributed architecture above. It is used in cases where existing domains are +to be federated. For example, different departments in a city operate their own +[Context Broker]{.HTML-Keyboard}-based NGSI-LD infrastructure, but applications +are to enabled to easily access all available information using just one point +of access. The architecture works in the same way as the distributed +architecture, except that instead of simple [Context Sources]{.HTML-Keyboard}, +whole domains are registered with the respective [Context +Broker]{.HTML-Keyboard} as point of access. Typically, the domains will be +registered to the federation [Context Registry]{.HTML-Keyboard} on a more +coarse-grained level, providing scopes, in particular geographic scopes, that +can then be matched to the scopes provided in the requests. For example, instead +of registering individual entities like buildings, the domain would be +registered with having information about entities of type building within a +geographic area. Applications then query or subscribe for entities within a +geographic scope, e.g. buildings in a certain area of the city. The [Federation +Broker]{.HTML-Keyboard} discovers the domain [Context Brokers]{.HTML-Keyboard} +that can provide relevant information, forwards the request to these [Context +Brokers]{.HTML-Keyboard} and aggregates the results, so the application gets the +result in the same way as in the centralized and distributed cases. + + + +::: FL + +::: + +::: TF +Figure: Federated architecture +::: + + + +A domain itself can use a centralized or distributed architecture or could even +utilize a federated architecture that federates sub-domains. + +As in the distributed case, it is also possible that applications discover +relevant domains through the federation-level [Context Registry]{.HTML-Keyboard} +and directly contact the [Context Brokers]{.HTML-Keyboard} in the individual +domains. + +#### 4.3.3.2 Registrations + +[Context Source Registrations]{.HTML-Keyboard} provide the basis for enabling +distributed and federated architectures. They need to contain all the relevant +information that allows [Context Brokers]{.HTML-Keyboard} to find the right +[Context Source]{.HTML-Keyboard} for consuming or provisioning Context +information. + +To find suitable [Context Sources]{.HTML-Keyboard} for an NGSI-LD request, it +has to be checked whether a [Context Source]{.HTML-Keyboard} manages potentially +relevant Entity information. Thus, Context Sources specify what Entity +information they manage, which is then matched with what is specified in the +request. [Context Source Registrations]{.HTML-Keyboard} can specify Entities on +different granularity levels. The highest granularity is to specify each Entity +with its identifier, type and the names of available Attributes. Depending on +the dynamics of the Entities stored in the [Context Source]{.HTML-Keyboard} this +may require many updates to the respective [Context Source +Registration]{.HTML-Keyboard}, on the other hand the [Context +Source]{.HTML-Keyboard} is only contacted regarding information it actually has. +Further levels of granularity are only providing Entity id and type. If the +identifier of differnt Entities follow a common pattern, this pattern can be +provided instead of a specific identifier, or only the Entity Type. It is also +possible to specify only the names of the Attributes. If the level of +granularity is coarse-grained as in the last examples, there will be few upates +to the [Context Source Registration]{.HTML-Keyboard}, but there may be many +requests for Entities that would fit according to Entity Type or Attribute Name, +which are not actually available in the [Context Source]{.HTML-Keyboard}. Thus, +the granularity level relates to a trade-off between [Context Source +Registration]{.HTML-Keyboard} and unsuccessful requests for Entity information +to [Context Source]{.HTML-Keyboard}. + +Beyond the specification of Entities, [Context Source +Registrations]{.HTML-Keyboard} can include additional information for filtering, +e.g. a geographic area specified by coordinates in which all Entities can be +found. This can be matched to queries in which a geographic filter is specified. +Only in case there is an overlap, the [Context Source]{.HTML-Keyboard} has to be +contacted. + +One fundamental concept underpinning all of the prototypical architectures +described above is the idea that Entity data, even regarding the same Entity, +does not need to be centralized within a single [Context +Broker]{.HTML-Keyboard}. When reading context information, a [Context +Broker]{.HTML-Keyboard} can be used as a single point of access to retrieve +Entity data found distributed across multiple associated [Context +Brokers]{.HTML-Keyboard} each receiving a **context consumption** request. +Similarly, when modifying an Entity, a single request to a [Context +Broker]{.HTML-Keyboard} may result in the operation being distributed and +different parts of that Entity being updated across multiple [Context +Brokers]{.HTML-Keyboard} each receiving a **context provision** request. + +As indicated above, it is possible to have mixed architectures, i.e. +Distribution and Federation Brokers can also store Entity information locally as +in the centralized case. + +However, there are cases, where some more control is needed where Entity data is +stored. To enable this, there are different types of registrations: + +- **additive registrations**: For additive registrations, the [Context + Broker]{.HTML-Keyboard} is permitted to hold context data about the Entities + and Attributes locally itself, and also obtain data from external sources. + Context provisioning operations are serviced both locally by the [Context + Broker]{.HTML-Keyboard} itself, and also distributed on to the registered + sources. There a two different sub-types of additive registrations: + - An **inclusive** [Context Source Registration]{.HTML-Keyboard} specifies + that the [Context Broker]{.HTML-Keyboard} considers all registered [Context + Sources]{.HTML-Keyboard} as equals and will distribute operations to those + [Context Sources]{.HTML-Keyboard} even if relevant context data is available + directly within the [Context Broker]{.HTML-Keyboard} itself (in which case, + all results will be integrated in the final response). This is the default + mode of operation. + - An **auxiliary** [Context Source Registration]{.HTML-Keyboard} never + overrides data held directly within a [Context Broker]{.HTML-Keyboard}. + Auxiliary distributed operations are limited to context information + consumption operations (see Clause+++clause-4+++root.4). Context data from + auxiliary context sources is only included if it is supplementary to the + context data otherwise available to the [Context Broker]{.HTML-Keyboard}. +- **proxied registrations**: For proxied registrations, the [Context + Broker]{.HTML-Keyboard} itself is not permitted to hold context data about the + registered Entities and Attributes locally (thus all registered context data + is obtained from the external registered sources). Unregistered Attributes of + an Entity are permitted to be held locally; when context provisioning + operations are received, registered Attributes are distributed on to the + registered sources and never serviced directly by the [Context + Broker]{.HTML-Keyboard} itself. There a two different sub-types of proxied + registrations: + - An **exclusive** [Context Source Registration]{.HTML-Keyboard} specifies + that all of the registered context data is held in a single location + external to the [Context Broker]{.HTML-Keyboard}. The [Context + Broker]{.HTML-Keyboard} itself holds no data locally about the registered + Attributes and no overlapping proxied [Context Source + Registrations]{.HTML-Keyboard} are to be supported for the same combination + of registered Attributes on the Entity. An **exclusive** registration always + relates to specific Attributes of a single Entity. + - A **redirect** [Context Source Registration]{.HTML-Keyboard} also specifies + that the registered context data is held in a location external to the + [Context Broker]{.HTML-Keyboard}. Redicect registrations can also refer to + whole Entities or all Entities of certain Entity Types. Unlike in the + exclusive case, multiple distinct **redirect** registrations can apply at + the same time. + +A more detailed specification of registration types can be found in +Clause+++clause-9+++root.3. + +#### 4.3.3.3 Distributed request execution + +##### 4.3.3.3.1 Introduction + +Figure+++below sketches the different steps of a request from a [Context +Consumer]{.HTML-Keyboard} that requires a distributed execution. The +[Distribution Broker]{.HTML-Keyboard} (or [Federation Broker]{.HTML-Keyboard}) +sends a discovery request to the [Context Registry]{.HTML-Keyboard}. The +[Context Registry]{.HTML-Keyboard} **matches** the discovery request with its +[Context Source Registrations]{.HTML-Keyboard} and returns the fitting ones. +Based on the information in the [Context Source Registrations]{.HTML-Keyboard}, +the Distribution Broker]{.HTML-Keyboard} **contacts** [Context +Sources]{.HTML-Keyboard}, forwarding adapted requests to the [Context +Sources]{.HTML-Keyboard}. They return their results. The Distribution Broker +**aggregates** the results, possibly retrieves additional information and +filters the results, before returning the final result to the [Context +Consumer]{.HTML-Keyboard}. + + + +::: FL + +::: + +::: TF +Figure: Executing distributed operations +::: + + + +In case the request form the [Context Consumer]{.HTML-Keyboard} is a +Subscription, the request to the Context Registry is a [Context Source +Registration Subscription]{.HTML-Keyboard} to the [Context +Registry]{.HTML-Keyboard}, which will send a Notification with the currently +relevant [Context Source Registrations]{.HTML-Keyboard}. On any change regarding +the relevant [Context Source Registrations]{.HTML-Keyboard}, it will send +another Notification with the updates. + +##### 4.3.3.3.2 Matching registrations + +When querying [Context Source Registrations]{.HTML-Keyboard}, the Entities +and/or Attributes specified in the request have to be matched against the set of +[Context Source Registrations]{.HTML-Keyboard}, extracting the matching ones. + +The relevant specification information in the query for [Context Source +Registrations]{.HTML-Keyboard} are the selector of Entity Types (if present), +the list of Entity identifiers (if present), the id pattern (if present) and the +list of Attribute names (if present). + +At least one of the following elements has to be present: a. selector of Entity +Types; or b. list of Attribute names. + +There is a match, if the following conditions apply: + +- If present, the selector of Entity Types, Entity identifiers and id pattern + match at least one of those specified in the [Context Source + Registrations]{.HTML-Keyboard}. +- If present, the Attribute identifiers match the Attributes (combination of + Properties and Relationships) specified in the in the [Context Source + Registrations]{.HTML-Keyboard}. + +If a condition is not present, it is considered to apply. + +The detailed conditions of matching can be found in Clause+++clause-9+++root.4. + +The [Context Source Registrations]{.HTML-Keyboard} that have been successfully +matched, are then filtered according to further condidtions specified in the +query, e.g. the geographic location specified in geographic coordinates. Only +those matching all filter conditions are returned as a result. + +##### 4.3.3.3.3 Contacting context sources + +Based on the information in the [Context Source Registrations]{.HTML-Keyboard}, +the [Distribution Broker]{.HTML-Keyboard} adapts the request. Only information +actually provided by the [Context Source]{.HTML-Keyboard} is to be retrieved, +e.g. if the original requests targets Attributes a, b and c, but the [Context +Source]{.HTML-Keyboard}, according to its [Context Source +Registrations]{.HTML-Keyboard}, only provides a and c, then only Attributes a +and c are requested. + +If Entities can be distributed across multiple [Context +Sources]{.HTML-Keyboard}, filters are not forwarded, as Entities first need to +be assembled before filters can be applied. If, however, it is known that each +Entity is in its entirety stored in a single [Context Source], the filters can +be forewarded, making the overall processing more efficient. + +The adapted request can only be forwarded to the [Context +Sources]{.HTML-Keyboard}, if the required operation is supported. If not, a +possible alternative request based on different operation or multiple requests +using different operations can be used by the [Distribution +Broker]{.HTML-Keyboard}. If there is no alternative in such a case, the overall +request partially fails, as requests to other [Context Sources]{.HTML-Keyboard} +can be successful. + +In some cases, the [Context Source Registration]{.HTML-Keyboard} contains +additional information, e.g. headers to be added. Finally, the request(s) are +sent to the endpoint given in the [Context Source Registration]{.HTML-Keyboard}. + +Additional information on what needs to be done when contacting [Context +Sources]{.HTML-Keyboard} is specified in Clause+++clause-9+++root.5. + +##### 4.3.3.3.4 Aggregating and processing of results + +The Entity information retrieved from the [Context Sources]{.HTML-Keyboard} is +aggregated. In case individual Entities can be distributed across different +[Context Sources]{.HTML-Keyboard}, additional retrieval steps can be necessary +to ensure that the relevant Entity information is there, before applying the +filters. If the same Entity information is available from different [Context +Sources]{.HTML-Keyboard} timestamps are compared to provide the most recent one. +Once all information has been aggregated and fitlered, the result is returned to +the [Context Consumer]{.HTML-Keyboard}. + +### 4.3.4 JSON-LD + +#### 4.3.4.1 Introduction + +NGSI-LD serialization is based on JSON-LD [i.12], a JSON-based format for +serializing Linked Data and a representation of RDF. The _`@context`_ in JSON-LD +is used to expand terms, provided as short-hand strings, to concepts, specified +as URIs, and vice versa, to compact URIs into terms. The motivation is to have, +on the one hand, unique terms, on the other hand, a compact, easily readable +representation based on short terms. NGSI-LD defines the terms of its vocabulary +in the core _`@context`_, users can define further terms relevant for their data +model in a user _`@context`_, in particular the Entity Types and Attribute names +they need. + +#### 4.3.4.2 Expansion and compaction + +NGSI-LD API operations allow clients to use short-hand strings as non-qualified +names, particularly for [Attribute]{.HTML-Definition} or [Entity +Type]{.HTML-Definition} names. For instance, an API client can refer to the term +["Store"]{.HTML-Code} as a non-qualified type name. When executing API +operations where content is provided in the body, NGSI-LD systems expand terms +to URIs based on a provided user _`@context`_, or, as a fall-back, on the +NGSI-LD core _`@context`_, in order to obtain and store Fully Qualified Names, +e.g. ["https://uri.etsi.org/ngsi-ld/example/Store"]{.HTML-Code}. The originally +used short name is not stored anywhere, nor the user _`@context`_ provided as +part of the request. + +Likewise, when returning results, NGSI-LD systems compact URIs (Fully Qualified +Names) to short terms in order to provide short-hand strings to [Context +Consumers]{.Keyboard}, based on the user _`@context`_ provided as part of the +request, not any previously used user _`@context`_. + +The term to URI expansion or compaction is performed using an _`@context`_ as +described by the JSON-LD specification [i.12], section 5.1. + + + +>>> [!tip] EXAMPLE: + +The following NGSI-LD Entity is provided as input + +``` json +{ + "id": "urn:ngsi-ld:Store:001", + "type": "Store", + "storeName": { + "type": "Property", + "value": "Checker Market" + } +} +``` + +together with the following user _`@context`_ that contains the NGSI-LD core _`@context`_ + +``` json +{ + "@context": [ + { + "Store": "https://uri.etsi.org/ngsi-ld/example/Store", + "storeName": "https://uri.etsi.org/ngsi-ld/example/storeName" + }, + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +the NGSI-LD content will be expanded to the following representation + +``` json +[ + { + "@id": "urn:ngsi-ld:Store:001", + "@type": [ + "https://uri.etsi.org/ngsi-ld/example/Store" + ], + "https://uri.etsi.org/ngsi-ld/example/storeName": [ + { + "@type": [ + "https://uri.etsi.org/ngsi-ld/Property" + ], + "https://uri.etsi.org/ngsi-ld/hasValue": [ + { + "@value": "Checker Market" + } + ] + } + ], + } +] +``` + +which is only used internally and is not visible to the user. + +Using the following user _`@context`_ when retrieveing the Entity + +``` json +{ + "@context": [ + { + "Shop": "https://uri.etsi.org/ngsi-ld/example/Store", + "shopName": "https://uri.etsi.org/ngsi-ld/example/storeName" + }, + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + +results in the following compacted representation, where "store" has been replaced by "shop". + +``` json +{ + "id": "urn:ngsi-ld:Store:001", + "type": "Shop", + "shopName": { + "type": "Property", + "value": "Checker Market" + } +} +``` + +>>> + + + +#### 4.3.4.3 Core \@context + +The core NGSI-LD (JSON-LD) _`@context`_ is defined as a JSON-LD _`@context`_ +which contains: + +- The core terms needed to uniquely represent the key concepts defined by the + NGSI-LD Information Model. +- The terms needed to uniquely represent all the members that define the + API-related Data Types. +- A fallback _`@vocab`_ rule to expand or compact user-defined terms to a + default URI, in case there is no other possible expansion or compaction as per + the current _`@context`_. +- The core NGSI-LD _`@context`_ defines the term ["id"]{.HTML-Code}, which is + mapped to _`@id`_, and the term ["type"]{.HTML-Code}, which is mapped to + _`@type`_. Since _`@id`_ and _`@type`_ are what is typically used in JSON-LD, + they may also be used in NGSI-LD requests instead of ["id"]{.HTML-Code} and + ["type"]{.HTML-Code} respectively, wherever this is applicable. In NGSI-LD + responses, only ["id"]{.HTML-Code} and ["type"]{.HTML-Code} are used. + +NGSI-LD compliant implementations support such core _`@context`_, which is +considered implicitly present when processing or generating context information. +Furthermore, the Core _`@context`_ is protected and remainsD immutable and +invariant during expansion or compaction of terms. Therefore, and as per the +JSON-LD processing rules [i.12], when processing NGSI-LD content, +implementations are to consider the core _`@context`_ as if it were in the +**last** position of the _`@context`_ array. Nonetheless, for the sake of +compatibility and cleanness, data providers are expected to generate JSON-LD +content that conveys the core _`@context`_ in the last position. + +For the avoidance of doubt, when rendering NGSI-LD Elements, the core +_`@context`_ is always treated as if it had been originally placed **in the last +position**, so that, if needed, upstream JSON-LD processors can properly expand +as NGSI-LD or override the resulting JSON-LD documents provided by API +implementations. + +The NGSI-LD core _`@context`_ is publicly available at +[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld) +and contains all the terms as specified in annex b. + +#### 4.3.4.4 User \@context + +In addition to the terms defined by the core NGSI-LD _`@context`_ (as specified +in annex B), a user _`@context`_ is to be provided that contains the following +terms: + +- One term associated to the Entity Type, mapping the Entity Type name with its + Type Identifier (URI). +- One term associated to the name of each Attribute or any of its subclasses + mapping the Property name with its Property Identifier (URI). + +Generally, a user _`@context`_ is provided with each request. However, in +addition to the core _`@context`_, NGSI-LD systems can allow the specfication of +a user default _`@context`_ that then is to be used as _`@context`_, if no user +_`@context`_ is provided with the request. + +## 4.4 API overview + +The NGSI-LD API provides operations to manage, find and access both the current +state of [Entities]{.HTML-Keyboard}, as well as the [Temporal Evolution of +Entities]{.HTML-Keyboard}. Table+++below introduces the structure of the NGSI-LD +API. It is structured into the Core API, the Temporal API, the Distributed API, +the Registry API, the Snapshot API and the Table+++below introduces the +structure of the NGSI-LD API. It is structured into the Core API, the Temporal +API, the Distributed API, the Registry API, the Snapshot API and the +JSON-LDContext API. These APIs are substructured into functional groups that are +further described in Table+++below. Each of the functional groups consists of a +number operations, which are described in detail in Clause+++clause-6+++root. + +The Distributed API includes the distributed versions of the Core API and the +Temporal API operations, plus a number of supporting operations needed in the +distributed case, e.g. for enabling efficient pagination across Entity +information distributed across multiple [Context Sources]{.HTML-Keyboard}. The +provided distributed functionalities are generally the same from a user +perspective, but implementing them can require taking into account additional +aspects, and, unlike most of their local counterparts, their execution can +possibly only be partially successful. + +The Registry API provides the operations to manage and discover the [Context +Sources]{.HTML-Keyboard} that can be relevant for a distributed request. + +The Snapshot API includes all operations related to snapshots. Snapshots allow +creating a consistent (within the limits of the possibly distributed NGSI-LD +system) view of the Entities selected by the queries. It allows consuming these +Entities, but also using provision operations for making available predicted and +simulated information, e.g. as needed for digital twins. + +The JSONLDContext API implements the capability of storing and serving +_`@contexts`_ to clients. The stored _`@contexts`_ can be managed by clients +directly. Clients can store custom user _`@contexts`_ at the Context Broker, +effectively using the Context Broker as an _`@context`_ server. + +**Table 4.4-1: NGSI-LD API structure** + + + +::: TAL ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| API | Functionality | ++=======================+=========================================================================================================================================================================+ +| Core API | _Context Information Provision_ - The provision operations allow [Context Procuders]{.HTML-Keyboard} to provide context information, i.e. to create Entities and | +| | Attributes, to update Attribues and to delete Entities and Attributes. The operations are typically implemented by [Context Brokers]{.HTML-Keyboard}. Furthermore, | +| | there are operations for checking for which Entity Types and Attributes there are Entities available in the NGSI-LD system. | +| | | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Context Information Consumption_ - The cconsumption operations allow [Context Consumers]{.HTML-Keyboard} to consume context information, i.e. to retrieve a specific | +| | Entity or to query for Entities that fulfil the specified criteria, thus discovering and retrieving these Entities in a single step. | +| | | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Context Information Subscription_ - The subscription operations allow [Context Consumers]{.HTML-Keyboard} to subscribe to context information and to receive | +| | notifications as specified in the conditions, i.e. when new matching Entites or Attributes become available, when Attributes are updated, or when Entities or Attributes| +| | are no longer available. In addition, there are operations for managing subscriptions. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Temporal API | _Temporal Context Information Provision_ - The temporal provision operations allow [Context Procuders]{.HTML-Keyboard} to provide temporal context information, i.e. to | +| (optional) | create the Temporal Evolution of Entities and Attributes, to append information to the Temporal Evolution of Entities and Attributes, to delete the Temporal Evolution | +| | of Entities and Attributes, and to correct or delete elements of the Temporal Evolution of Attributes. In many cases [Context Brokers]{.HTML-Keyboard} automatically | +| | add changes to an Entity received through the Core API to the Temporal Evolution of the same Entity. | +| | | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Temporal Context Information Consumption_ - The temporal consumption operations allow [Context Consumers]{.HTML-Keyboard} to consume temporal context information, i.e.| +| | to retrieve the Temporal Evolution of a specific Entity or to query for the Temporal Evolution of Entities that fulfil the specified criteria, thus discovering and | +| | retrieving the Temporal Evolution of Entities in a single step. | +| | | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Distributed API | _Distributed Context Information Provision_ - The distributed provision operations support the same general functionality as the corresponding ones in the Core API. | +| (optional) | They need to be implemented by [Context Brokers]{.HTML-Keyboard} that can act as [Distribution Brokers]{.HTML-Keyboard} or [Federation Brokers]{.HTML-Keyboard}. | +| | | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Distributed Context Information Consumption_ - The distributed consumption operations support the same general functionality as the corresponding ones in the Core API.| +| | They need to be implemented by [Context Brokers]{.HTML-Keyboard} that can act as [Distribution Brokers]{.HTML-Keyboard} or [Federation Brokers]{.HTML-Keyboard}. | +| | | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Distributed Context Information Subscription_ - The distributed subscription operations support the same general functionality as the corresponding ones in the Core | +| | API. They need to be implemented by [Context Brokers]{.HTML-Keyboard} that can act as [Distribution Brokers]{.HTML-Keyboard} or [Federation Brokers]{.HTML-Keyboard}. | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Distributed Temporal Context Information Provision_ - The distributed temporal provision operations support the same general functionality as the corresponding ones in| +| | the Core API. They need to be implemented by [Context Brokers]{.HTML-Keyboard} that can act as [Distribution Brokers]{.HTML-Keyboard} or | +| | [Federation Brokers]{.HTML-Keyboard}. | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Distributed Temporal Context Information Consumption_ - The distributed temporal consumption operations support the same general functionality as the corresponding | +| | ones in the Core API. They need to be implemented by [Context Brokers]{.HTML-Keyboard} that can act as [Distribution Brokers]{.HTML-Keyboard} or | +| | [Federation Brokers]{.HTML-Keyboard}. | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Support operations for distributed operations_ - The support operations enable more consistent pagination in the distributed case and the prevention of request loops. | +| | | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Registry API | _Context Source Registration_ - The registration operations allow the registration of Context Sources and updating and deleting Context Source Registrations. | +| (optional, required | | +| for distributed | | +| operations) +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Context Source Discovery_ - The discovery operations allow retrieving and discovering Context Source Registrations. | +| | | +| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | _Context Source Registration Subscription_ - The subscription operations allow subscribing to Context Source Registrations and receiving notifications. They support | +| | distributed subscriptions as any relevant changes in the [Context Sources]{.HTML-Keyboard} needs to be taken into account when monitoring subscription. In addition, | +| | there are operations for updating and deleting Context Source Registration Subscriptions. | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Snapshot API | _Snapshot Management_ - The snapshot management operations enable creating snapshots, retrieving the snapshot status, updating the expiration time, deleting snapshots, | +| (optional) | and cloning snapshots, i.e. duplicating the snapshot, e.g. to update them separately based on simulations making different assumptions. | +| | | +| | The information contained in a snapshot is updated using the Core API operations, but applied to the respective snapshot. | +| | | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| JSONLDContext API | _JSON-LD_ _`@context`_ _Management_ - The _`@context`_ managment operations allow storing user JSON-LD _`@context`_, listing available _`@context`_, | +| (optional) | serving stored JSON-LD _`@context`_ and deleting user JSON-LD _`@context`_. In addition, a [Context Broker]{.HTML-Keyboard} can make | +| | _cached_ JSON-LD _`@context`_ visible, which can then be deleted, or deleted and updated in a single step, in case the source JSON-LD _`@context`_ has changed. | +| | | ++-----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + diff --git a/md/clause-5.md b/md/clause-5.md new file mode 100644 index 0000000000000000000000000000000000000000..9fcd735827ea8ff97db34d3833407c0050e68443 --- /dev/null +++ b/md/clause-5.md @@ -0,0 +1,5825 @@ +# 5 Context information and representation + +## 5.1 Introduction + +Clause+++root defines data structures and operations of the NGSI-LD API. No +specific binding is assumed. + +## 5.2 NGSI-LD modelling, data types and data representation + +### 5.2.1 Introduction + +This clause describes how to represent data within NGSI-LD implementations. + +### 5.2.2 Data representation + +#### 5.2.2.1 Introduction + +This clause defines the general requirements for data representation (both input +and output) across all endpoints of the NGSI-LD API. + +#### 5.2.2.2 Supported text encodings + +NGSI-LD implementations shall support the **UTF-8** text encoding format. To +avoid interoperability problems, applications shall provide JSON content encoded +using UTF-8 and NGSI-LD systems shall also expose such JSON content using UTF-8. + +#### 5.2.2.3 Supported names + +Even though the JSON serialization format allows inclusion of any character in +the Unicode space, NGSI-LD restricts Entity Type names, Property names and +Relationship names to the following ABNF grammar: + + + +```text +nameChar = unicodeNumber / unicodeLetter +nameChar =/ %x5F ; Representing the underscore character _ +name = unicodeLetter *nameChar +``` + + + +- _unicodeNumber_ is any Unicode character that has _Number_ as a Category + [n.2]. With Unicode-capable regular expression (RegEx) parsers, such a + character may be matched by [\\p{N}]{.HTML-Code}. +- _unicodeLetter_ is any Unicode character that has _Letter_ as a Category + [n.2]. With Unicode-capable regular expression (RegEx) parsers, such a + character may be matched by [\\p{L}]{.HTML-Code}. + +In order to avoid name clashing, names can be prefixed as specified by the +following BNF grammar: + + + +```text +prefix = unicodeLetter *nameChar +name =/ prefix %x3A unicodeLetter *nameChar ; prefix:name +``` + + + +When receiving a JSON-LD object with a name (Type, Property, Relationship) +including characters different than those expressed above, implementations +should raise an error of type [BadRequestData]{.HTML-Error}. + +#### 5.2.2.4 Supported data types for Values + +Compliant NGSI-LD implementations shall support the following data types for +representing Values: + +- All the JSON native data types as mandated by IETF RFC 8259 [n.3], section 3. +- All the GeoJSON _Geometries_ [n.4] with the exception of _GeometryCollection_. +- **DateTime** string for encoding a timestamp, i.e. a calendar date together + with a time of day, expressed in **UTC**, using the ISO 8601 [n.5] Complete + Representation and in particular using the 'Extended Format', as described + below: + - The timestamp shall be a string containing _Year_, _Month_, _Day_, _Hours_, + _Minutes_, _Seconds and time zone_ components using the format + [YYYY-MM-DDThh:mm:ssZ]{.HTML-Code} as defined in ISO 8601 [n.5]. In this + representation, the character ["-"]{.HTML-Code} is used to separate the + calendar date components, the character ["T"]{.HTML-Code} is used to + indicate the start of the time-of-day portion, the character + [":"]{.HTML-Code} is used to separate the time-of-day components, and the + trailing character ["Z"]{.HTML-Code} is used to convey the time zone. + - All the referred components shall appear in the string; reduced + representations are not permitted. + - The Seconds component may optionally contain a decimal fraction. In this + case the string shall contain two integer digits, followed by a decimal + point and then one or more fractional digits, up to a maximum of six. For + example, [YYYY-MM-DDThh:mm:ss.ssssssZ]{.HTML-Code}. In requests, also a + comma instead of a decimal point may be used as separator for compatibility + reasons. + + + +>>> [!note] NOTE 1: + +In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [n.5] +states that it is the preferred option. However, in practice the decimal point +is more commonly used _._ + +>>> + + + +- The trailing timestamp component shall contain the time zone related + information and shall always be equal to the character ["Z"]{.HTML-Code}. + Therefore, all timestamps shall be expressed in **UTC**. + +- **Date** string for encoding a calendar date. It uses ISO 8601 [n.5] Complete + Representation using the 'Extended Format', as described below: + - It shall be a string containing _Year_, _Month_, _Day_ components using the + format [YYYY-MM-DD]{.HTML-Code} as defined in ISO 8601 [n.5]. In this + representation, the character ["-"]{.HTML-Code} is used to separate the + calendar date components. + - All the referred components shall appear in the string; reduced + representations are not permitted. + +- **Time** string for encoding a local time expressed in **UTC**. It uses ISO + 8601 [n.5] Complete Representation using the 'Extended Format', as described + below: + - It shall be a string containing _Hours_, _Minutes_ and _Seconds_ components + using the format [hh:mm:ssZ]{.HTML-Code} as defined in ISO 8601 [n.5]. In + this representation, the character [":"]{.HTML-Code} is used to separate the + local time components. + - All the referred components shall appear in the string; reduced + representations are not permitted. + - The _Seconds_ component may optionally contain a decimal fraction. In this + case the string shall contain two integer digits, followed by a decimal + point and then one or more fractional digits, up to a maximum of six. For + example, [hh:mm:ss.ssssssZ]{.HTML-Code}. In requests, also a comma instead + of a decimal point may be used as separator for compatibility reasons. + + + +>>> [!note] NOTE 2: + +In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [n.5] +states that it is the preferred option. However, in practice the decimal point +is more commonly used. + +>>> + + + +- The string shall not contain expressions of the difference between local time + and UTC. All representations shall be interpreted as being expressed in + **UTC**. + +- URI as mandated by ISO 8601 [n.5], Appendix A, production rule named 'URI'. + +Implementations may support additional data types different to those enumerated +above, for instance: + +- JSON-LD typed value (i.e. a string as the lexical form of the value together + with a type, defined by an XSD base type or more generally an IRI). +- JSON-LD structured value (e.g. a set, a list). + +#### 5.2.2.5 Supported content + +In principle, context information providers can publish any kind of data +serialized in JSON and encoded in UTF-8. Nonetheless, to avoid security problems +caused by script injection attacks or other attack vectors, implementations +should consider that the incoming data from a client may contain the following +characters: + +- [%x3C; <]{.HTML-Code} +- [%x3E; >]{.HTML-Code} +- [%x22; "]{.HTML-Code} +- [%x27; ']{.HTML-Code} +- [%x3D; =]{.HTML-Code} +- [%x3B; ;]{.HTML-Code} +- [%x28; (]{.HTML-Code} +- [%x29; )]{.HTML-Code} + +When receiving entities (context information) encoded in JSON format and +containing values that include the above characters, implementations should +decide how to resolve the possible security problems that may be generated by +the data. In all cases, implementations shall preserve the representation of the +content of the values provided by the context information providers and return +the original content when replying to **context consumption requests**. + +If implementations decide to raise an error, the error shall be +[BadRequestData]{.HTML-Error}. + +### 5.2.3 Entity Types + +All NGSI-LD Entities have at least one Entity Type. From NGSI-LD API version +1.5.1 onwards, multiple Entity Types for any Entity are supported. An Entity is +uniquely identified by its _`id`_, so whenever information is provided for an +Entity with a given _`id`_, it is considered part of the same Entity, regardless +of the Entity Type(s) specified. To avoid unexpected behaviour, Entity Types can +be implicitly added by all operations that update or append attributes. There is +no operation to remove Entity Types from an Entity. The philosophy here is to +assume that an Entity always had all Entity Types, but possibly not all Entity +Types have previously been known in the system. The only option to remove an +Entity Type is to delete the Entity and re-create it with the same _`id`_. +Alternatively, a batch upsert with ["replace"]{.HTML-Code} update mode can be +used, as described in Clause+++clause-10+++10.3.3. + +### 5.2.4 Simple Attributes / temporal Attributes + +NGSI-LD defines the following Properties of type _TemporalProperty_ that shall +be supported by implementations: + +- ["observedAt"]{.HTML-Code} is defined as the temporal Property at which a + certain Attribute became valid or was observed. For example, a temperature + Value was measured by the sensor at this point in time. +- ["createdAt"]{.HTML-Code} is defined as the temporal Property at which the + Entity or Attribute was entered into an NGSI-LD system. +- ["modifiedAt"]{.HTML-Code} is defined as the temporal Property at which the + Entity or Attribute was last modified in an NGSI-LD system, e.g. in order to + correct a previously entered incorrect value. +- ["deletedAt"]{.HTML-Code} is defined as the temporal Property at which the + Entity or Attribute was deleted from an NGSI-LD system. +- ["expiresAt"]{.HTML-Code} is defined as the temporal Property at which the + Entity, Attribute, CSourceRegistration, Subscription or Snapshot should be + deleted from an NGSI-LD system. +- ["lastUsedAt"]{.HTML-Code} is defined as the temporal Property at which a + Snapshot has been most recently used, i.e. when the most recent operation has + been executed on this Snapshot. + +Temporal Properties in NGSI-LD shall be represented based on the _DateTime_ data +type as mandated by Clause+++root.2.2.4. + + + +>>> [!note] NOTE 1: + +For simplicity reasons, a _TemporalProperty_ is represented only by its Value, +i.e. no _Properties_ of _TemporalProperty_ nor _Relationships_ of +_TemporalProperty_ can be conveyed. In more formal language, a +_TemporalProperty_ does not allow reification. + +>>> + + + + + +>>> [!note] NOTE 2: + +It is important to remark that the term _TemporalProperty_ has been reserved for +the semantic tagging of non-reified structural timestamps ( _`observedAt`_ , +_`createdAt`_ , _`modifiedAt`_, _`deletedAt`_ , _`expiresAt`_ ), which capture the +temporal evolution of Attributes. **Only such structural timestamps can be used +as** _`timeproperty`_ **in Temporal Queries as mandated by +Clause+++clause-7+++7.2.6** . + +>>> + + + + + +>>> [!note] NOTE 3: + +User-defined Properties whose value is a time value ( _Date, DateTime or Time_ ) +are defined as _Property_ , not as _TemporalProperty_ , and are serialized in +NGSI-LD as shown in Annex C, Clause+++annex-c+++C.5. + +>>> + + + +Whenever a _TemporalProperty_ value is unknown by a registered [Context +Source]{.HTML-Keyboard}, the Property shall be omitted rather than sending an +error response. + +In some cases, it is desirable to create an Entity (or Attribute) which is only +expected to be stored for a defined period of time. Thereafter such an Entity +(or Attribute) should be removed, and can be safely deleted from the context via +an automatic garbage collection process. + +In this regard NGSI-LD defines the following system Property of type +_TemporalProperty_ that shall be supported by implementations: + +- ["expiresAt"]{.HTML-Code} is defined as the system temporal Property at which + a certain Entity or Attribute shall become invalid and may be automatically + removed from the [Context Broker]{.HTML-Keyboard}. For example, an Alert + Entity was created to last for 24 hours and should be removed after this + period of time. + +It should be noted that clean-up processes will only run periodically, and will +be dependent upon the [Context Broker]{.HTML-Keyboard} implementation, therefore +final deletion will always lag the _`expiresAt`_ timestamp to a certain extent. +Furthermore, _`expiresAt`_ only applies to the local storage, i.e. the Entity or +Attribute is to be deleted locally, but not on other [Context +Sources]{.HTML-Keyboard} or [Context Broker]{.HTML-Keyboard} hosting such Entity +information, where no _`expiresAt`_ timestamp is present. Thus _`expiresAt`_ is +not considered to be intrinsic to the Entity or Attribute, but only applies to +the storage of the Entity or Attribute respectively. As it pertains to a system +function (the deletion from storage after the expiration time), it is considered +to be a system attribute. + +### 5.2.5 Matrix of all Attributes + +Table+++below gives a list of all defined attribute names within NGSI-LD data +types. User-defined terms within the user _`@context`_ may reuse these terms +**as is**, but shall avoid amending the definition these attribute names, since +the Core _`@context`_ definition always has priority, and will override any +changes defined in the user _`@context`_. + + + +::: TH +Table: Matrix of all Attributes +::: + +::: TAL ++--------------------------------+-----------------------------------------------------------------------+ +| Name | Data Type using the attribute | ++================================+=======================================================================+ +| accept | Endpoint | ++--------------------------------+-----------------------------------------------------------------------+ +| aggrParams | Query | ++--------------------------------+-----------------------------------------------------------------------+ +| aggrMethods | AggregationParams, TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| aggrPeriodDuration | AggregationParams, TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| attributeCount | Attribute | ++--------------------------------+-----------------------------------------------------------------------+ +| attributeDetails | EntityTypeInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| attributeList | AttributeList | ++--------------------------------+-----------------------------------------------------------------------+ +| attributeName | Attribute, NotUpdatedResult | ++--------------------------------+-----------------------------------------------------------------------+ +| attributeNames | EntityType | ++--------------------------------+-----------------------------------------------------------------------+ +| attributeTypes | Attribute, EntityTypeInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| attributes | NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| attrs | Query | ++--------------------------------+-----------------------------------------------------------------------+ +| cacheDuration | RegistrationManagementInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| collation | OrderingParams | ++--------------------------------+-----------------------------------------------------------------------+ +| containedBy | Query | ++--------------------------------+-----------------------------------------------------------------------+ +| contextSourceAlias | ContextSourceIdentity, CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| contextSourceExtras | ContextSourceIdentity | ++--------------------------------+-----------------------------------------------------------------------+ +| contextSourceInfo | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| contextSourceTimeAt | ContextSourceIdentity | ++--------------------------------+-----------------------------------------------------------------------+ +| contextSourceUptime | ContextSourceIdentity | ++--------------------------------+-----------------------------------------------------------------------+ +| cooldown | Endpoint, RegistrationManagementInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| coordinates | GeoParams, OrderingParams | ++--------------------------------+-----------------------------------------------------------------------+ +| createdAt | Property, Relationship, GeoProperty, ListProperty, ListRelationship, | +| | LanguageProperty, JsonProperty, VocabProperty, Entity, Snapshot | +| | | ++--------------------------------+-----------------------------------------------------------------------+ +| createEntityMap | Query | ++--------------------------------+-----------------------------------------------------------------------+ +| csf | Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| data | CSourceNotification, Notification | ++--------------------------------+-----------------------------------------------------------------------+ +| datasetId | Property, Relationship, GeoProperty, ListProperty, | +| | ListRelationship, LanguageProperty, JsonProperty, | +| | VocabProperty, Subscription, CSourceRegistration, Query | ++--------------------------------+-----------------------------------------------------------------------+ +| deletedAt | Property, Relationship, GeoProperty, ListProperty, ListRelationship, | +| | LanguageProperty, JsonProperty, VocabProperty, Subscription | +| | | ++--------------------------------+-----------------------------------------------------------------------+ +| description | CSourceRegistration, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| endAt | TimeIntervalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| endTimeAt | TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| endpoint | CSourceRegistration, Snapshot, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| entities | Query, RegistrationInfo, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| entity | Relationship | ++--------------------------------+-----------------------------------------------------------------------+ +| entityCount | EntityTypeInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| entityId | EntityError | ++--------------------------------+-----------------------------------------------------------------------+ +| entityList | ListRelationship | ++--------------------------------+-----------------------------------------------------------------------+ +| entityMap | EntityMap | ++--------------------------------+-----------------------------------------------------------------------+ +| entityMapLifetime | Query | ++--------------------------------+-----------------------------------------------------------------------+ +| error | EntityError | ++--------------------------------+-----------------------------------------------------------------------+ +| errors | OperationResult | ++--------------------------------+-----------------------------------------------------------------------+ +| expandValues | Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| expiresAt | Property, Relationship, GeoProperty, ListProperty, ListRelationship, | +| | LanguageProperty, JsonProperty, VocabProperty, Subscription, | +| | CSourceRegistration, SnapshotNotification, EntityMap, Entity, | +| | Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| features | FeatureCollection | ++--------------------------------+-----------------------------------------------------------------------+ +| format | NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| geoQ | Feature, Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| geometry | OrderingParams, GeoParams | ++--------------------------------+-----------------------------------------------------------------------+ +| geoproperty | GeoParams | ++--------------------------------+-----------------------------------------------------------------------+ +| georel | GeoParams | ++--------------------------------+-----------------------------------------------------------------------+ +| idPattern | EntitySelector, EntityInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| information | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| instanceId | Property, Relationship, GeoProperty, ListProperty, ListRelationship, | +| | LanguageProperty, JsonProperty, VocabProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| isActive | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| join | Query, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| joinLevel | Query, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| json | JsonProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| jsonKeys | Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| jsonldContext | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| jsons | JsonProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| key | KeyValuePair | ++--------------------------------+-----------------------------------------------------------------------+ +| lang | Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| languageMap | LanguageProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| languageMaps | LanguageProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| lastFailure | CSourceRegistration, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| lastN | TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| lastNotification | NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| lastSuccess | CSourceRegistration, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| lastUsedAt | Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| linkedMaps | EntityMap | ++--------------------------------+-----------------------------------------------------------------------+ +| localOnly | Query, RegistrationMangementInfo, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| location | Entity, CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| management | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| managementInterval | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| mode | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| modifiedAt | Property, Relationship, GeoProperty, ListProperty, ListRelationship, | +| | LanguageProperty, JsonProperty, VocabProperty, Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| ngsildproof | Property, Relationship, GeoProperty, ListProperty, ListRelationship, | +| | LanguageProperty, JsonProperty, VocabProperty | +| | | ++--------------------------------+-----------------------------------------------------------------------+ +| ngsildConformance | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| notification | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| notificationTrigger | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| notifiedAt | CSourceNotification, Notification, SnapshotNotification | ++--------------------------------+-----------------------------------------------------------------------+ +| notifierInfo | Endpoint | ++--------------------------------+-----------------------------------------------------------------------+ +| notUpdated | UpdateResult | ++--------------------------------+-----------------------------------------------------------------------+ +| object | Relationship | ++--------------------------------+-----------------------------------------------------------------------+ +| objectList | ListRelationship | ++--------------------------------+-----------------------------------------------------------------------+ +| objectLists | ListRelationship | ++--------------------------------+-----------------------------------------------------------------------+ +| objects | Relationship | ++--------------------------------+-----------------------------------------------------------------------+ +| objectType | Relationship, ListRelationship | ++--------------------------------+-----------------------------------------------------------------------+ +| observationInterval | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| observationSpace | CSourceRegistration, Entity | ++--------------------------------+-----------------------------------------------------------------------+ +| observedAt | Property, Relationship, GeoProperty, ListProperty, ListRelationship, | +| | LanguageProperty, JsonProperty, VocabProperty | +| | | ++--------------------------------+-----------------------------------------------------------------------+ +| omit | Query, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| operations | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| operationSpace | CSourceRegistration, Entity | ++--------------------------------+-----------------------------------------------------------------------+ +| orderBy | OrderingParams | ++--------------------------------+-----------------------------------------------------------------------+ +| ordering | Query | ++--------------------------------+-----------------------------------------------------------------------+ +| pick | Query, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| previousJson | JsonProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| previousLanguageMap | LanguageProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| previousObject | Relationship | ++--------------------------------+-----------------------------------------------------------------------+ +| previousObjectList | ListRelationship | ++--------------------------------+-----------------------------------------------------------------------+ +| previousValue | Property, GeoProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| previousValueList | ListProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| previousVocab | VocabProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| problemDetails | ExecutionResult | ++--------------------------------+-----------------------------------------------------------------------+ +| properties | Feature | ++--------------------------------+-----------------------------------------------------------------------+ +| propertyNames | RegistrationInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| q | Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| reason | NotUpdatedResult | ++--------------------------------+-----------------------------------------------------------------------+ +| receiverInfo | Endpoint, Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| refreshRate | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| registrationId | NotUpdatedResult, EntityError | ++--------------------------------+-----------------------------------------------------------------------+ +| registrationName | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| relationshipNames | RegistrationInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| resultStatus | ExecutionResult | ++--------------------------------+-----------------------------------------------------------------------+ +| scope | CSourceRegistration, Entity | ++--------------------------------+-----------------------------------------------------------------------+ +| scopeQ | Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| showChanges | NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotId | SnapshotNotification | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotLifetime | Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotPriority | SnapshotNotification, Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotQueries | Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotQueriesDetails | Snapshot, SnapshotNotification | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotStatus | Snapshot, SnapshotNotification | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotTemporalQueries | Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| snapshotTemporalQueriesDetails | Snapshot | ++--------------------------------+-----------------------------------------------------------------------+ +| splitEntities | Query | ++--------------------------------+-----------------------------------------------------------------------+ +| startAt | TimeIntervalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| status | CSourceRegistration, NotificationParams, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| subscriptionId | CSourceNotification, Notification | ++--------------------------------+-----------------------------------------------------------------------+ +| subscriptionName | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| success | OperationResult | ++--------------------------------+-----------------------------------------------------------------------+ +| sysAttrs | NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| temporalQ | Query, Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| temporalSnapshotQueriesDetails | SnapshotNotification | ++--------------------------------+-----------------------------------------------------------------------+ +| tenant | CSourceRegistration | ++--------------------------------+-----------------------------------------------------------------------+ +| throttling | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| timeAt | TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| timeInterval | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +| timeout | Endpoint, RegistrationManagementInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| timeproperty | TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| timerel | TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ +| timesFailed | CSourceRegistration, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| timesSent | CSourceRegistration, NotificationParams | ++--------------------------------+-----------------------------------------------------------------------+ +| triggerReason | CSourceNotification | ++--------------------------------+-----------------------------------------------------------------------+ +| typeList | EntityTypeList | ++--------------------------------+-----------------------------------------------------------------------+ +| typeName | EntityType, EntityTypeInfo | ++--------------------------------+-----------------------------------------------------------------------+ +| typeNames | Attribute | ++--------------------------------+-----------------------------------------------------------------------+ +| unitCode | Property, ListProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| updated | UpdateResult | ++--------------------------------+-----------------------------------------------------------------------+ +| uri | Endpoint | ++--------------------------------+-----------------------------------------------------------------------+ +| value | Property, GeoProperty, KeyValuePair | ++--------------------------------+-----------------------------------------------------------------------+ +| valueList | ListProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| valueLists | ListProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| values | Property, ListProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| valueType | Property, GeoProperty, ListProperty, | +| | LanguageProperty, JsonProperty, VocabProperty | +| | | ++--------------------------------+-----------------------------------------------------------------------+ +| vocab | VocabProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| vocabs | VocabProperty | ++--------------------------------+-----------------------------------------------------------------------+ +| watchedAttributes | Subscription | ++--------------------------------+-----------------------------------------------------------------------+ +::: + + + +Furthermore, the following additional attribute names are also defined in the +Core _`@context`_: + +- ["detail"]{.HTML-Code} and ["title"]{.HTML-Code} are used in Error responses + and retain their definitions from IETF RFC 7807 [n.6]. See + Clause+++clause-8+++8.3.3 + +- ["avg"]{.HTML-Code}, ["distinctCount"]{.HTML-Code}, ["max"]{.HTML-Code}, + ["min"]{.HTML-Code}, ["stddev"]{.HTML-Code}, ["sum"]{.HTML-Code}, + ["sumsq"]{.HTML-Code}, ["totalCount"]{.HTML-Code} are used by the Aggregated + temporal representation of an Entity. See Clause+++root.3.2.7 + +- ["bbox"]{.HTML-Code}, ["properties"]{.HTML-Code}, ["coordinates"]{.HTML-Code} + are used in geographic operations and retain their standard GeoJSON-LD + definitions [i.13]. + +- ["dataset"]{.HTML-Code} is used in the representation of an Entity in the + **simplified format** to separate the _`datasetId`_ of multi-attributes. see + Clause+++root.3.2.4 + +- ["langString"]{.HTML-Code} is defined to retain its standard RDF datatype + [n.7]. + +### 5.2.6 Data types + +#### 5.2.6.1 Introduction + +Implementations shall support the data types defined by the clauses below. For +each member defined by each data type (including nested ones) a term shall be +added to the Core _`@context`_, as mandated by Clause+++root.3.2.1. + +None of the members described admit a _`null`_ value directly, as when a JSON-LD +processor encounters _`null`_, the associated entry or value is always removed +when expanding the JSON-LD document. + +However, in the context of a partial update or merge operation (see +Clause+++clause-8+++8.4.2 and Clause+++clause-8+++8.4.3), an NGSI-LD Null shall +be used to indicate the removal of a target member, as explained in +Clause+++clause-8+++8.4.3. In all other cases, implementations shall raise an +error of type [BadRequestData]{.HTML-Error} if an NGSI-LD Null value is +encountered. + +As _`null`_ cannot be used as a value in JSON-LD, there is still the possibility +of using a JSON null literal [{"@type": "@json", "@value": +null}]{.HTML-Code} instead. JSON literals are not to be expanded in JSON-LD and +thus the respective element is not removed during JSON-LD expansion. + +Non-normative JSON Schema [i.14] definitions of the referred data types are also +available at [i.15]. + +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.1], +which extends the use of characters to Unicode characters [n.2] beyond the ASCII +character set, enabling the support of languages other than English. + +#### 5.2.6.2 Common members + +The JSON-LD representation of NGSI-LD Entity, Property, Relationship, [Context +Source Registration]{.HTML-Keyboard} and Subscription can include the common +members described by Table+++below. + +Those members are read-only, and shall be automatically generated by NGSI-LD +implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + +In query or retrieve operations implementations shall only generate common +members (Table+++below) when the [Context Consumer]{.HTML-Keyboard} explicitly +asks for their inclusion. For example, [i.16] ~clause 6.4.5 defines the +mechanism offered by the HTTP binding for such purpose. + + + +::: TH +Table: Common members of NGSI-LD elements +::: + +::: TAL ++-------------+-------------+-----------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=============+=============+===================================+=============+=======================================================================================================================================================================================================================+ +| createdAt | string | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Entity creation timestamp. See Clause+++root.2.4. | ++-------------+-------------+-----------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| deletedAt | string | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Entity deletion timestamp. See Clause+++root.2.4. It is only used in notifications reporting deletions and in the temporal representation of Entities, Properties and Relationships (Clause+++root.3.2.5) | ++-------------+-------------+-----------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| modifiedAt | string | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Entity last modification timestamp. See Clause+++root.2.4. | ++-------------+-------------+-----------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 5.2.6.3 \@context + +When encoding NGSI-LD Entities, [Context Source Registrations]{.HTML-Keyboard}, +Subscriptions and Notifications, as pure JSON-LD (MIME type +["application/ld+json"),]{.HTML-Code} an array (flattened to a single string if +necessary), containing a user _`@context`_ where present, and the core +_`@context`_ (as described in Clause+++root.3.2.1) shall be included as a +special member of the corresponding JSON-LD Object. Table+++below gives a +precise definition of this special member + + + +::: TH +Table: JSON-LD \@context tagged member +::: + +::: TAL ++-------------+---------------------------------+-------------------------------+-------------+----------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=============+=================================+===============================+=============+======================+ +| \@context | URI, JSON Object, or JSON Array | See [n.8], ~clause 5.1 | 0..1 | JSON-LD _`@context`_.| ++-------------+---------------------------------+-------------------------------+-------------+----------------------+ +::: + + + +#### 5.2.6.4 Representational data types + +##### 5.2.6.4.1 Entity + +This type represents the data needed to define an NGSI-LD Entity to be +represented as in Clause+++root.3. + +On an Entity, NGSI-LD defines the following Attributes of type _GeoProperty_ +(Clause+++root.2.6.4.5). Preferably these Attribute names should be used if they +semantically fit, but if necessary, additional Attribute names of type +_GeoProperty_ can be defined by [Context Producers]{.HTML-Keyboard}: + +- ["location"]{.HTML-Code} is defined as the geospatial Property representing + the geographic location of the Entity, e.g. the location of a building or the + current location of a car. +- ["observationSpace"]{.HTML-Code} is defined as the geospatial Property + representing the geographic location that is being observed, e.g. by a sensor. + For example, in the case of a camera, the location of the camera and the + observation space are different and can be disjoint. +- ["operationSpace"]{.HTML-Code} is defined as the geospatial Property + representing the geographic location in which an Entity, e.g. an actuator is + active. For example, a crane can have a certain operation space. + +The defined _GeoProperties_ can also be used as part of [Context Source +Registrations]{.HTML-Keyboard} (Clause+++root.2.6.5.3). In this case they +represent locations in which Entities with the respective geospatial Properties +are contained. For example, a [Context Source]{.HTML-Keyboard} that monitors the +location of cars in a city may be represented by a [Context Source +Registration]{.HTML-Keyboard} whose Attribute _`location`_ corresponds to the +space of the city in which the location of cars is monitored. + +The supported JSON members shall follow the requirements provided in +Table+++below + + + +::: TH +Table: NGSI-LD Entity data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| id | String | Valid URI | 1 | Entity ID. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| type | String or String[] | | 1 | Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the Entity. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| location | GeoProperty | See datatype definition | 0..1 | Default geospatial Property of an entity. | +| | | in Clause+++root.2.6.4.5 | | representing the geographic location of the Entity itself. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observationSpace | GeoProperty | See datatype definition | 0..1 | Geospatial Property representing the geographic area that is being observed | +| | | in Clause+++root.2.6.4.5 | | by the Entity. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| operationSpace | GeoProperty | See datatype definition | 0..1 | Geospatial Property representing the geographic area in which an Entity | +| | | in Clause+++root.2.6.4.5 | | is active | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| scope | String or String[] | See Clause+++root.2.7 | 0..1 | Scope. | +| | | | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of an Entity. | +| | (see note) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of an Entity. | +| | (see note) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of an Entity. | +| | (see note) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of an Entity. | +| | (see note) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of an Entity. | +| | (see note) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of an Entity. | +| | (see note) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of an Entity. | +| | (see note) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of an Entity. | +| | (see note) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.4.2 EntityTemporal + +This datatype represents the [Temporal Evolution of an Entity]{.HTML-Keyboard}. + +This is the same datatype as mandated by Clause+++root.2.6.4.1 with the only +deviation that the representation of Properties and Relationships shall be the +temporal one, as defined in Clause+++root.3.2.5. Alternatively it is possible to +specify the EntityTemporal by using the "Simplified temporal representation of +an Entity", as defined in Clause+++root.3.2.6. + +##### 5.2.6.4.3 Property + +This type represents the data needed to define a _Property_. + +The supported JSON members shall follow the requirements provided in +Table+++below. The datatype definition defines all the required attributes for +the normalized format. In the concise format, the Attribute _`type`_ member can +be omitted as [type="Property"]{.HTML-Code} can be inferred from the presence of +the _`value`_ member. Furthermore, in the concise format of a _Property_, the +_`value`_ member cannot be a GeoJSON Object (as defined in +Clause+++root.2.6.4.5) as it would be interpreted as a _GeoProperty_ (see +Clause+++root.2.6.4.5). + + + +::: TH +Table: NGSI-LD Property data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["Property"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| value \ | Any JSON value as defined by IETF RFC 8259 [n.3] | See NGSI-LD Value definition | 1 | Property Value. | +| (see note 1) | | in Clause 3.1 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the Property. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the Property guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C, Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| unitCode | String | As mandated by [n.10] | 0..1 | Property Value's unit code. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| valueType | String | | 0..1 | The native JSON-LD _`@type`_ for the Property Value. A String Value which shall be type coerced | +| | | | | to a URI based on the supplied _`@context`_. See Clause+++root.2.4. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the Property. | +| | (see note 2) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a Property, the _`value`_ member is replaced with a _`values`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated Property _`value`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_Property_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD Property data type +::: + +::: TAL ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===============+====================================================+=================================================================================+=============+===========================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of Properties | 0..1 | URI uniquely identifying a Property instance as mandated by | +| | | | | Clause+++root.3.2.5 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| previousValue | Any JSON value as defined by IETF RFC 8259 [n.3] | Only used in Notifications, if the _`showChanges`_ option | 0..1 | Previous Property Value. | +| | | is explicitly requested. | | | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +::: + + + +Furthermore, a Property shall never include the following members: + +**Prohibited** + +- ["entity"]{.HTML-Code} shall never be present, as it is used during inline + [Linked Entity]{.HTML-Keyboard} **retrieval** to define the target Entity of a + _Relationship's_ object. +- ["entityIdSealed"]{.HTML-Code} and ["entityTypeSealed"]{.HTML-Code} shall + never be present, unless the Property name is ["ngsildproof"]{.HTML-Code}. +- ["entityList"]{.HTML-Code} shall never be present, as it is used during inline + [Linked Entity]{.HTML-Keyboard} **retrieval** to define the target Entities of + a _ListRelationship's_ object. +- ["json"]{.HTML-Code} and ["previousJson"]{.HTML-Code} shall never be present, + as they define a _JsonProperty_ value. +- ["languageMap"]{.HTML-Code} and ["previousLanguageMap"]{.HTML-Code} shall + never be present, as they define a _LanguageProperty_ value. +- ["object"]{.HTML-Code} and ["previousObject"]{.HTML-Code} shall never be + present, as they define a _Relationship's_ object URI. +- ["objectList"]{.HTML-Code} and ["previousObjectList"]{.HTML-Code} shall never + be present, as they define an ordered array of _Relationship_ object URIs. +- ["valueList"]{.HTML-Code} and ["previousValueList"]{.HTML-Code} shall never be + present, as they define an ordered array of _Property_ values. +- ["vocab"]{.HTML-Code} and ["previousVocab"]{.HTML-Code} shall never be + present, as they define a _VocabProperty_ value. + +##### 5.2.6.4.4 Relationship + +This type represents the data needed to define a _Relationship_. + +The supported JSON members shall follow the requirements provided in +Table+++below. The datatype definition defines all the required attributes for +the normalized format. In the concise format, the Attribute _`type`_ member can +be omitted as [type="Relationship"]{.HTML-Code} can be inferred from the +presence of the _`object`_ member. See Clause+++root.2.6.4.6 + + + +::: TH +Table: NGSI-LD Relationship data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["Relationship"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| object \ | String or String[] | Valid URI or an Array of Valid URIs | 1 | Relationship's target object. | +| (see note 1) | | ["Relationship"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the Property. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the Relationship guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C, Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| objectType | String or String[] | | 0..1 | Node Type of the Relationship's target object. Both short hand string(s) (type name) | +| | | | | or URI(s) are allowed. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the Relationship. | +| | (see note 2) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a Relationship, the _`object`_ member is replaced with a _`objects`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated Relationship _`object`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_Relationship_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD Relationship data type +::: + +::: TAL ++----------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++================+=================================+============================================================================================+===========================+===========================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++----------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++----------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------------+ +| entity | Entity or Entity[] \ | See datatype definition in Clause+++root.2.6.4.1 | 0..1 | An inline Entity obtained by Linked Entity Retrieval, corresponding | +| | (see note) | | | to the Relationship's target object. See Clause+++clause-7+++7.7.2. | +| | | Only used in Linked Entity Retrieval, if the *join=inline* option | | | +| | | is explicitly requested | | | ++----------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of Properties | 0..1 | URI uniquely identifying a Relationship instance as mandated by | +| | | | | Clause+++root.3.2.5 | ++----------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++----------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------------+ +| previousObject | String | Valid URI. Only used in Notifications, if the _`showChanges`_ option | 0..1 | Previous Relationship's target object. | +| | | is explicitly requested | | | ++----------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------------+ +| >>> [!note] NOTE: | +| | +| one-to-N *Relationships* expand to an array of Entity elements, since there can be more than one target object URI specified. | +| | +| >>> | ++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +Furthermore, a Relationship shall never include the following members: + +**Prohibited** + +- ["entityIdSealed"]{.HTML-Code} and ["entityTypeSealed"]{.HTML-Code} shall + never be present. +- ["entityList"]{.HTML-Code} shall never be present, as it is used during inline + [Linked Entity]{.HTML-Keyboard} **retrieval** to define the target Entities of + a _ListRelationship's_ object. +- ["languageMap"]{.HTML-Code} and ["previousLanguageMap"]{.HTML-Code} shall + never be present, as they define a _LanguageProperty_ value. +- ["json"]{.HTML-Code} and ["previousJson"]{.HTML-Code} shall never be present, + as they define a _JsonProperty_ value. +- ["objectList"]{.HTML-Code} and ["previousObjectList"]{.HTML-Code} shall never + be present, as they define an ordered array of _Relationship_ object URIs. +- ["unitCode"]{.HTML-Code} shall never be present, as _Relationships_ are + unitless. +- ["value"]{.HTML-Code} and ["previousValue"]{.HTML-Code} shall never be + present, as they define a _Property_ value. +- ["valueList"]{.HTML-Code} and ["previousValueList"]{.HTML-Code} shall never be + present, as they define an ordered array of _Property_ values. +- ["vocab"]{.HTML-Code} and ["previousVocab"]{.HTML-Code} shall never be + present, as they define a _VocabProperty_ value. + +##### 5.2.6.4.5 GeoProperty + +This type represents the data needed to define a _GeoProperty_ + +Geospatial Properties in NGSI-LD shall be represented using **GeoJSON** +Geometries [n.4]. With the aim of highlighting and encoding those Properties +which convey geospatial characteristics, NGSI-LD defines a special type of +Property named _GeoProperty_. + +When dealing with NGSI-LD Entities, implementations shall interpret JSON-LD +nodes of type _GeoProperty_ just as conventional Properties but with the +additional requirement that the Value corresponding to such Property shall be a +GeoJSON Geometry. All the Geometries defined by [n.4] are allowed except +_GeometryCollection_. In addition, implementations should take the necessary +steps to create the corresponding geo-indexes so that information can be +properly returned when geo-queries are executed. + +**Representation of GeoJSON Geometries in JSON-LD** + +There are certain types of GeoJSON geometries, for instance GeoJSON Polygon, +whose coordinates are represented using nested array structures (through the +_`coordinates`_ member). Such representation may introduce serialization +problems when transforming JSON-LD content into RDF graphs. + +Also, when using whole GeoJSON geometries (consisting of _`type`_ and +_`coordinates`_) in an NGSI-LD document, its JSON syntax is only preserved in +the regular JSON-LD representation (with separate _`@context`_), but not in an +expanded representation. To handle resulting problems, optionally, whole GeoJSON +geometries can be represented as a JSON string. + +Implementations shall accept the referred encoded string value, if and only if, +it can be parsed into a JSON Object, as mandated by IETF RFC 8259 [n.3], meeting +the syntax and restrictions mandated by IETF RFC 7946 [n.4] when representing a +valid Geometry of the type specified. + +For the avoidance of doubt, regular encodings of GeoJSON geometries (as JSON +Object) shall also be accepted by implementations, but [Context +Producers]{.HTML-Keyboard} should consider the implications in terms of RDF +compatibility. + +GeoJSON coordinates shall be considered as consisting of values of a JSON-LD +floating point **number** data type. The degree of precision of a latitude and +longitude (and optional altitude) held within a [Context Broker]{.HTML-Keyboard} +will depend upon the implementation. Implementors should note that the GeoJSON +specification itself recommends 6 decimal places for latitude and longitude +which equates to roughly 10cm of precision. + +The supported JSON members shall follow the requirements provided in +Table+++below. The datatype definition defines all the required attributes for +the normalized format. In the concise format, the Attribute _`type`_ member can +be omitted as [type="GeoProperty"]{.HTML-Code} can be inferred from the presence +of the _`value`_ member holding a GeoJSON _Geometry_ [n.4]. See +Clause+++root.2.6.4.6. + + + +::: TH +Table: NGSI-LD GeoProperty data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["GeoProperty"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| value \ | Any JSON value as defined by IETF RFC 8259 [n.3] | See NGSI-LD Value definition | 1 | Geolocation encoded as GeoJSON [n.4]. | +| (see note 1) | | in Clause 3.1 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the Property. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the GeoProperty guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C, Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| valueType | String | | 0..1 | The native JSON-LD _`@type`_ for the GeoProperty Value. A String Value which shall be type coerced | +| | | | | to a URI based on the supplied _`@context`_. See Clause+++root.2.4. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the GeoProperty. | +| | (see note 2) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a GeoProperty, the _`value`_ member is replaced with a _`values`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated Property _`value`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_GeoProperty_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD GeoProperty data type +::: + +::: TAL ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===============+====================================================+=================================================================================+=============+===========================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of GeoProperties | 0..1 | URI uniquely identifying a _GeoProperty_ instance as mandated by | +| | | | | Clause+++root.3.2.5 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| previousValue | Any JSON value as defined by IETF RFC 8259 [n.3] | Only used in Notifications, if the *showChanges* option is explicitly requested | 0..1 | Previous GeoProperty Value. | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +::: + + + +In addition to the list of prohibited attribute names for a Property described +in in Clause+++root.2.6.4.3, GeoProperties shall never include the following +members: + +**Prohibited** + +- ["unitCode"]{.HTML-Code} shall never be present, as _GeoProperties_ are + unitless. + +##### 5.2.6.4.6 LanguageProperty + +This type represents the data needed to define a _LanguageProperty_. Note that +in case of concise format, the _type_ can be omitted as +[type="LanguageProperty"]{.HTML-Code} can be inferred from the presence of the +_`languageMap`_ member. See Clause+++root.2.6.4.6 + +The supported JSON members shall follow the requirements provided in +Table+++below. + +Note that the value of the _LanguageProperty_ _`languageMap`_ member, shall be a +JSON object consisting of a series of key-value pairs where the keys shall be +JSON strings representing IETF RFC 5646 [n.11] language codes or the JSON-LD +["@none"]{.HTML-Code} for representing the default when no more specific +language is found. The value of each key-value pair be JSON strings or arrays of +JSON strings. + +Additionally, the _`languageMap`_ encoding [{"@none": +"urn:ngsi-ld:null"}]{.HTML-Code} shall be used to represent an NGSI-LD Null +during partial update patch and merge patch (see Clause+++clause-8+++8.4.2 and +Clause+++clause-8+++8.4.3) and for representing deleted Language Properties in +notifications and in temporal evolutions. + + + +::: TH +Table: NGSI-LD LanguageProperty data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["LanguageProperty"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| languageMap \ | JSON Object | A set of key-value pairs whose keys | 1 | String Property Values defined in multiple natural languages | +| (see note 1) | | shall be strings representing IETF | | | +| | | RFC 5646 [n.11] language codes and | | | +| | | whose values shall be JSON strings | | | +| | | or arrays of JSON strings | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the Property. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the LanguageProperty guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C, Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| valueType | String | It shall be equal to | 0..1 | The native JSON-LD _`@type`_ for the _`languageMap`_ atttibute. A String Value which shall be type | +| | | ["langString"]{.HTML-Code} | | coerced to a URI based on the supplied _`@context`_. See Clause+++root.2.4. \ | +| | | | | (see note 2) | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the LanguageProperty. | +| | (see note 3) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a LanguageProperty, the _`languageMap`_ member is replaced with a _`languageMaps`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated LanguageProperty _`languageMap`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| The assigned _`@type`_ for language tagged strings is datatype URI: [http://www.w3.org/1999/02/22-rdf-syntax-ns#langString]{.HTML-Code} [n.7]. | +| | +| >>> | +| | +| >>> [!note] NOTE 3: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_LanguageProperty_ data structure are also defined. They are read-only and shall +be generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD LanguageProperty data type +::: + +::: TAL ++---------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=====================+====================================================+=================================================================================+=============+===========================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++---------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++---------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of LanguageProperties | 0..1 | URI uniquely identifying a _LanguageProperty_ instance as mandated by | +| | | | | Clause+++root.3.2.5 | ++---------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++---------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| previousLanguageMap | JSON Object | A set of key-value pairs whose keys shall be strings representing | 0..1 | Previous LanguageProperty's *languageMap.* | +| | | IETF RFC 5646 [n.11] language codes and whose values shall be JSON strings. | | | +| | | | | | +| | | | | | +| | | Only used in Notifications, if the _`showChanges`_ option | | | +| | | is explicitly requested | | | ++---------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +::: + + + +In addition to the list of prohibited attribute names for a Property described +in in Clause+++root.2.6.4.3, LanguageProperties shall never include the +following members: + +**Prohibited** + +- ["value"]{.HTML-Code} and ["previousValue"]{.HTML-Code} shall never be + present, as they define a _Property_ value, they are replaced by + ["languageMap"]{.HTML-Code} and ["previousLanguageMap"]{.HTML-Code} + respectively. +- ["unitCode"]{.HTML-Code} shall never be present, as _LanguageProperties_ are + unitless. + +##### 5.2.6.4.7 VocabProperty + +This type represents the data needed to define a +[VocabProperty]{.HTML-Keyboard}. In case of concise format, the _`type`_ can +omitted as [type="VocabProperty"]{.HTML-Code} can be inferred from the presence +of the _`vocab`_ member. See Clause+++root.2.6.4.6 + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: NGSI-LD VocabProperty data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["VocabProperty"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| vocab \ | String or String[] | | 1 | String Values which shall be type coerced to URIs based on the supplied _`@context`_. | +| (see note 1) | | | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the VocabProperty. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the VocabProperty guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C, Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| valueType | String | | 0..1 | The native JSON-LD _`@type`_ for the VocabProperty Value. A String Value which shall be type coerced | +| | | | | to a URI based on the supplied _`@context`_. See Clause+++root.2.4. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the VocabProperty. | +| | (see note 2) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a VocabProperty, the _`vocab`_ member is replaced with a _`vocabs`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated VocabProperty _`vocab`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_VocabProperty_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD VocabProperty data type +::: + +::: TAL ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===============+====================================================+=================================================================================+=============+===========================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of VocabProperties | 0..1 | URI uniquely identifying a _VocabProperty_ instance as mandated by | +| | | | | Clause+++root.3.2.5 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| previousVocab | String or String[] | Only used in Notifications, if the _`showChanges`_ option | 0..1 | Previous VocabProperty's _`vocab`_. | +| | | is explicitly requested | | | ++---------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +::: + + + +In addition to the list of prohibited attribute names for a Property described +in in Clause+++root.2.6.4.3, VocabProperties shall never include the following +members: + +**Prohibited** + +- ["value"]{.HTML-Code} and ["previousValue"]{.HTML-Code} shall never be + present, as they define a _Property_ value, they are replaced by + ["vocab"]{.HTML-Code} and ["previousVocab"]{.HTML-Code}: respectively. +- ["unitCode"]{.HTML-Code} shall never be present, as _VocabProperties_ are + unitless. + +##### 5.2.6.4.8 ListProperty + +This type represents the data needed to define a _ListProperty_. Note that in +case of concise format, the _`type`_ can be omitted as +[type="ListProperty"]{.HTML-Code} can be inferred from the presence of the +_`valueList`_ member. See Clause+++root.2.6.4.6 + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: NGSI-LD ListProperty data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["ListProperty"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| valueList \ | An array of JSON values as defined by IETF | See NGSI-LD Value definition in | 1 | Ordered array of Property Values | +| (see note 1) | RFC 8259 [n.3] | in Clause 3.1 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the ListProperty. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the ListProperty guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C, Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| valueType | String | | 0..1 | The native JSON-LD _`@type`_ for the ListProperty Value. A String Value which shall be type coerced | +| | | | | to a URI based on the supplied _`@context`_. See See Clause+++root.2.4. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the ListProperty. | +| | (see note 2) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a ListProperty, the _`valueList`_ member is replaced with a _`valueLists`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated ListProperty _`valueList`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | +| | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_ListProperty_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD ListProperty data type +::: + +::: TAL ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===================+====================================================+=================================================================================+=============+===========================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of VocabProperties | 0..1 | URI uniquely identifying a _ListProperty_ instance as mandated by | +| | | | | Clause+++root.3.2.5 | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| previousValueList | String or String[] | Only used in Notifications, if the _`showChanges`_ option | 0..1 | Previous ListProperty's _`valueList`_. | +| | | is explicitly requested. | | | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +::: + + + +In addition to the list of prohibited attribute names for a Property described +in in Clause+++root.2.6.4.3, ListProperties shall never include the following +members: + +**Prohibited** + +- ["value"]{.HTML-Code} and ["previousValue"]{.HTML-Code} shall never be + present, as they define a _Property_ value, they are replaced by + ["valueList"]{.HTML-Code} and ["previousValueList"]{.HTML-Code}: respectively. + +##### 5.2.6.4.9 ListRelationship + +This type represents the data needed to define a _ListRelationship_. Note that +in case of concise format, the _`type`_ can be omitted as +[type="ListRelationship"]{.HTML-Code} can be inferred from the presence of the +_`objectList`_ member. See Clause+++root.2.6.4.6 Note that the _`objectList`_ +may also be represented as an ordered array of Strings. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: NGSI-LD ListRelationship data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["Relationship"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| objectList \ | JSON Object[] or | In the normalized form, each array | 1 | Ordered array of Relationship target objects. | +| (see note 1) | String[] | element holds a JSON object containing | | | +| | | a single Attribute with a key called | | | +| | | ["objectList"]{.HTML-Code} where the | | | +| | | value is a valid URI | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the ListRelationship. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the ListRelationship guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C, Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| objectType | String or String[] | | 0..1 | Node Type of the ListRelationship's target objects. Both short hand string(s) (type name) | +| | | | | or URI(s) are allowed. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the ListRelationship. | +| | (see note 2) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a ListRelationship, the _`objectList`_ member is replaced with a _`objectLists`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated ListRelationship _`objectList`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_Relationship_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD ListRelationship data type +::: + +::: TAL ++---------------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=====================+=================================+============================================================================================+===========================+=====================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++---------------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++---------------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------+ +| entityList | Entity[] \ | See datatype definition in Clause+++root.2.6.4.1 | 0..1 | An array of inline Entities obtained by Linked Entity Retrieval, | +| | (see note) | | | corresponding to the *ListRelationship*'s target objects. See | +| | | Only used in Linked Entity Retrieval, if the _`join=inline`_ option | | Clause+++clause-7+++7.7.2. | +| | | is explicitly requested | | | ++---------------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of Properties | 0..1 | URI uniquely identifying a *ListRelationship* instance as mandated | +| | | | | by Clause+++root.3.2.5 | ++---------------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++---------------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------+ +| previousObjectList | String | Valid URI. Only used in Notifications, if the _`showChanges`_ option | 0..1 | Previous ListRelationship's target objects. | +| | | is explicitly requested. | | | ++---------------------+---------------------------------+--------------------------------------------------------------------------------------------+---------------------------+---------------------------------------------------------------------+ +| >>> [!note] NOTE: | +| | +| one-to-N *Relationships* expand to an array of Entity elements, since there can be more than one target object URI specified. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +In addition to the list of prohibited attribute names for a Relationship +described in in Clause+++root.2.6.4.4, ListRelationships shall never include the +following members: + +**Prohibited** + +- ["object"]{.HTML-Code} and ["previousObject"]{.HTML-Code} shall never be + present, as they define a _Relationship_ value, they are replaced by + ["objectList"]{.HTML-Code} and ["previousObjectList"]{.HTML-Code}: + respectively. +- ["entity"]{.HTML-Code} shall never be present, as it is used for Linked Entity + retrieval of _Relationship_, it is replaced by ["entityList"]{.HTML-Code}. + +##### 5.2.6.4.10 JsonProperty + +This type represents the data needed to define a _JsonProperty_. Note that in +case of concise format, the _`type`_ can be omitted as as +[type="JsonProperty"]{.HTML-Code} can be inferred from the presence of the +_`json`_ member. See Clause+++root.2.6.4.6 + +The supported JSON members shall follow the requirements provided in +Table+++below. + + +::: TH +Table: NGSI-LD JsonProperty data type definition +::: + +::: TAL ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String | It shall be equal to | 1 | Node type. | +| | | ["JsonProperty"]{.HTML-Code} | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| json \ | JSON | See NGSI-LD Value definition in | 1 | Raw unexpandable JSON which shall not be interpreted as JSON-LD using the supplied _`@context`_. | +| (see note 1) | | in Clause 3.1 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System temporal Property representing the expiration date for the storage of the JsonProperty. | +| | | | | See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ngsildproof | Property | Property with the non-reified | 0..1 | Cryptographic signature of the JsonProperty guaranteeing its integrity. | +| | | subproperties "entityIdSealed" and | | See Annex C Clause+++annex-c+++C.10 for an example. | +| | | "entityTypeSealed" as specified in | | | +| | | [n.9] The value of its "value" element | | | +| | | shall be an object containing | | | +| | | the W3C® Data integrity | | | +| | | "proof" structure [n.9]. | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| observedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp. See Clause+++root.2.4 | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| valueType | String | | 0..1 | The native JSON-LD _`@type`_ for the JsonProperty Value. A String Value which shall be type coerced | +| | | | | to a URI based on the supplied _`@context`_. See See Clause+++root.2.4. | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the JsonProperty. | +| | (see note 2) | in Clause+++root.2.6.4.9 | | | ++----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| In the temporal representation of a JsonProperty, the _`json`_ member is replaced with a _`jsons`_ member, which is an array of tuples, each consisting of a _DateTime_ timestamp, and the associated JsonProperty _`json`_ at that time. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_JsonProperty_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Producers]{.HTML-Keyboard}. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the NGSI-LD JsonProperty data type +::: + +::: TAL ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===================+====================================================+=================================================================================+=============+===========================================================================+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4 | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| deletedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated deletion timestamp. See Clause+++root.2.4 | +| | | | | | +| | | It is only used in notifications reporting deletions | | | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| instanceId | String | Valid URI. Only used in temporal representation of VocabProperties | 0..1 | URI uniquely identifying a _JsonProperty_ instance as mandated by | +| | | | | Clause+++root.3.2.5 | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +| previousJson | String or String[] | Only used in Notifications, if the _`showChanges`_ option | 0..1 | Previous JsonProperty's _`json`_. | +| | | is explicitly requested | | | ++-------------------+----------------------------------------------------+---------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------+ +::: + + + +In addition to the list of prohibited attribute names for a Property described +in in Clause+++root.2.6.4.3, JsonProperties shall never include the following +members: + +**Prohibited** + +- ["value"]{.HTML-Code} and ["previousValue"]{.HTML-Code} shall never be + present, as they define a _Property_ value, they are replaced by + ["json"]{.HTML-Code} and ["previousJson"]{.HTML-Code}: respectively. +- ["unitCode"]{.HTML-Code} shall never be present, as _JsonProperties_ are + unitless. + +#### 5.2.6.5 Operational data types + +##### 5.2.6.5.1 Query + +This datatype represents the information that is required in order to convey a +query when a "Query Entities" operation or a "Query Temporal Evolution of +Entities" operation is to be performed (as per Clause+++clause-10+++10.4.3 and +Clause+++clause-11+++11.3.3, respectively). + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: Query data type definition +::: + +::: TAL ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=====================+====================+============================================================================================================================+==============+================================================================================================+ +| type | String | It shall be equal to ["Query"]{.HTML-Code} | 1 | JSON-LD _`@type`_ | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| entities | EntitySelector[] | See data type definition in Clause+++root.2.6.6.2. Empty array (0 length) is not allowed | 0..1 | Entity IDs, id pattern and Entity types that shall be matched by | +| | | | | Entities in order to be retrieved. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| q | String | A valid query string as per Clause+++clause-7+++7.2.3 | 0..1 | Query that shall be matched by Entities in order to be retrieved. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| geoQ | GeoQuery | See data type definition in Clause+++root.2.6.5.2 | 0..1 | Geoquery that shall be matched by Entities in order be retrieved. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| scopeQ | String | See Clause+++clause-7+++7.2.5 | 0..1 | Scope query. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| temporalQ | TemporalQuery | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be present only for "Query | +| | | | | [Temporal Evolution of Entities]{.HTML-Keyboard}" operation (Clause+++clause-11+++11.3.3). | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| attrs | String[] | Attribute name as short hand strings or URIs. | 0..1 | A synonym for a combination of the *pick* and*q* members. **Deprecated** | +| | | | | | +| | | Empty array (0 length) is not allowed | | List of Attributes that shall be matched by Entities in order to be retrieved. | +| | | | | If not present all Attributes will be retrieved. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| omit | String[] | Entity member (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or a projected Attribute name) | 0..1 | When defined, the specified Entity members are removed from each Entity within the payload. | +| | | as a valid attribute projection language string as per Clause+++clause-7+++7.3.2. Empty array (0 length) is not allowed | | | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| pick | String[] | Entity member (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or a projected Attribute name) | 0..1 | When defined, every Entity within the payload body is reduced down to only contain | +| | | as a valid attribute projection language string as per Clause+++clause-7+++7.3.2. Empty array (0 length) is not allowed | | the specified Entity members. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| aggrParams | AggregationParams | See data type definition in Clause+++root.2.6.7.6. | 0..1 | Aggregation parameters required for supporting aggregation methods in to be present | +| | | | | only for "[QueryTemporal Evolution of Entities]{.HTML-Keyboard} " operation | +| | | | | (Clause+++clause-11+++11.3.3). \ | +| | | | | Only applicable if ["aggregatedValues"]{.HTML-Code} is present in the | +| | | | | _`format`_ or _`options`_ parameter. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| csf | String | A valid query string as per Clause+++clause-7+++7.2.3 | 0..1 | Context source filter that shall be matched by | +| | | | | [Context Source Registrations]{.HTML-Keyboard} describing [Context Sources]{.HTML-Keyboard} | +| | | | | to be used for retrieving Entities. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| containedBy | String[] | Comma separated list of URIs. Empty array (0 length) is not allowed | 0..1 | List of entity ids which have previously been encountered whilst retrieving the Entity Graph. | +| | | | | | +| | | | | Only applicable if _`joinLevel`_ is present. | +| | | | | | +| | | | | Only applicable for the "Retrieve Entity" (Clause+++clause-10+++10.4.2) and "Query Entities" | +| | | | | operations (Clause+++clause-10+++10.4.3). | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| createEntityMap | Boolean | | 0..1 | If _`true`_, the location of the EntityMap used in the operation is returned in the response. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| datasetId | String[] | Valid URIs,["@none"]{.HTML-Code} for including the default Attribute instances. | 0..1 | Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute | +| | | | | as per Clause+++clause-8+++8.5. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| expandValues | String | Comma separated list of attribute names | 0..1 | Values of the identified attributes should be expanded against the supplied _`@context`_ | +| | | | | using JSON-LD type coercion prior to executing the query. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| entityMapLifetime | String | String representing a duration in ISO 8601 [n.5] format | 0..1 | Suggested duration for which the requester wants the EntityMap to exist. | +| | | | | The actual expiresAt time of the EntityMap shall be set by the Context Broker | +| | | | | or Context Source, possibly overriding the requested duration. Only applicable | +| | | | | if _`entityMap`_ is set to _`true`_ | +| | | | | | +| | | | | | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| jsonKeys | String | Comma separate list of attribute names | 0..1 | Values of the identified attributes are to be considered uninterpretable as JSON-LD and | +| | | | | should not be expanded against the supplied _`@context`_ using JSON-LD type coercion prior | +| | | | | to executing the query. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| join | String | It shall be one of: ["flat"]{.HTML-Code}, ["inline"]{.HTML-Code}, ["@none"]{.HTML-Code} | 0..1 | String representing the type of [Linked Entity]{.HTML-Keyboard} retrieval to apply. | +| | | | | | +| | | | | By default, it will be ["@none".]{.HTML-Code} | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| joinLevel | Number | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML-Keyboard} retrieval to apply. Default is 1. | +| | | | | Only applicable if _`join`_ parameter is ["flat"]{.HTML-Code}, or ["inline"]{.HTML-Code}. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| lang | String | A natural language filter in the form of a IETF RFC 5646 [n.11] language code | 0..1 | Language filter to be applied to the query (Clause+++clause-7+++7.2.7). | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| ordering | OrderingParams | See data type definition in Clause+++root.2.6.7.5 | 0..1 | When defined, the Entities returned in the payload shall be ordered according | +| | | | | to the members defined. | +| | | | | | +| | | | | This only applies if the operation is limited to the local scope. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| splitEntities | Boolean | default decided by implementation; it should be configurable. The parameter does not apply in case | 0..1 | If _`true`_ it is assumed that single Entities are distributed between different | +| | | the parameter _`local`_ is _`true`_ or the query applies to a Snapshot | | Context Brokers and/or Context Sources and this has to be taken into account when | +| | | | | applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). | +| | | | | If _`false`_ it is expected that Context Broker and/or Context Source | +| | | | | always have complete Entities, which allows applying filters locally. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.5.2 Subscription + +This datatype represents a Context Subscription. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: Subscription data type definition +::: + +::: TAL ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=====================+====================+============================================================================================================================+==============+================================================================================================+ +| id | String | Valid URI | 0..1 | Subscription identifier (JSON-LD _`@id`_). Generated at creation time, if it is not | +| | | | | provided, it will be assigned during subscription process and returned to client. | +| | | | | | +| | | | | It cannot be later modified in update operations. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["Subscription"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| entities | EntitySelector[] | See data type definition in Clause+++root.2.6.6.2. Empty array (0 length) is not allowed. | 0..1 | Entities subscribed. | +| | | | | | +| | | Mandatory if _`timeInterval`_ is present, unless the execution of the request is limited to local scope | | | +| | | (see Clause+++clause-8+++8.6) | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| notification | NotificationParams | See data type definition in Clause+++root.2.6.7.3 | 1 | Notification details. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| notificationTrigger | String[] | Valid notification triggers are ["entityCreated"]{.HTML-Code}, ["entityUpdated"]{.HTML-Code}, | 0..1 | The notification triggers listed indicate what kind of changes shall trigger a notification. | +| | | ["entityDeleted"]{.HTML-Code}, ["attributeCreated"]{.HTML-Code}, | | If not present, the default is the combination ["attributeCreated"]{.HTML-Code} | +| | | ["attributeUpdated"]{.HTML-Code}, ["attributeDeleted"]{.HTML-Code} | | and ["attributeUpdated"]{.HTML-Code}. ["entityUpdated"]{.HTML-Code} is equivalent to | +| | | | | the combination ["attributeCreated"]{.HTML-Code}, ["attributeUpdated"]{.HTML-Code} | +| | | | | and ["attributeDeleted"]{.HTML-Code}. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| watchedAttributes | String[] | Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed. | 0..1 | Watched Attributes (Properties or Relationships). If not defined it means any Attribute. | +| | | | | | +| | | if _`timeInterval`_ is present it shall not appear (0 cardinality) | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| q | String | A valid query string as per Clause+++clause-7+++7.2.3 | 0..1 | Query that shall be met by subscribed entities in order to trigger the notification. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| geoQ | GeoQuery | See data type definition in Clause+++root.2.6.7.2 | 0..1 | Geoquery that shall be met by subscribed entities in order to trigger the notification. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| scopeQ | String | See Clause+++clause-7+++7.2.5 | 0..1 | Scope query. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| temporalQ | TemporalQuery | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be used **only** in *Context Registration Subscriptions* | +| | | | | for matching [Context Source Registrations]{.HTML-Keyboard} of | +| | | | | [Context Sources]{.HTML-Keyboard} providing temporal information. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| csf | String | A valid query string as per Clause+++clause-7+++7.2.3 | 0..1 | Context source filter that shall be met by [Context Source Registrations]{.HTML-Keyboard} | +| | | | | describing [Context Sources]{.HTML-Keyboard} to be used for Entity Subscriptions. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| datasetId | String[] | Valid URIs,["@none"]{.HTML-Code} for including the default Attribute instances. | 0..1 | Specifies the datasetIds of the Attribute instances to be selected for each matched | +| | | | | Attribute as per Clause+++clause-8+++8.5. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| description | String | | 0..1 | Subscription description. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| expandValues | String | Comma separated list of attribute names | 0..1 | Values of the identified attributes should be expanded against | +| | | | | the supplied _`@context`_ using JSON-LD type coercion prior to executing the query. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Expiration date for the subscription. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| isActive | Boolean | _`true`_ by default | 0..1 | Allows clients to temporarily pause the subscription by making it inactive. | +| | | | | _`true`_ indicates that the Subscription is under operation. | +| | | | | _`false`_ indicates that the subscription is paused, and notifications shall | +| | | | | not be delivered. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| jsonKeys | String | Comma separate list of attribute names | 0..1 | Values of the identified attributes are to be considered uninterpretable as JSON-LD | +| | | | | and should not be expanded against the supplied | +| | | | | _`@context`_ using JSON-LD type coercion prior to executing the query. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| jsonldContext | String | Dereferenceable URI | 0..1 | The dereferenceable URI of the JSON-LD _`@context`_ to be used when sending a notification | +| | | | | resulting from the subscription. | +| | | | | If not provided, the _`@context`_ used for the subscription shall be used as a default. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| lang | String | A natural language filter in the form of a IETF RFC 5646 [n.11] language code | 0..1 | Language filter to be applied to the query (Clause+++clause-7+++7.2.7). | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| localOnly | Boolean | | 0..1 | If _`localOnly=true`_ then the subscription only pertains to the Entities stored locally. | +| | | | | In case the Subscription pertains to a Snapshot it is always local, regardless of whether | +| | | | | _`localOnly`_ is set to _`true`_ or not. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| ngsildConformance | String | A semantically versioned string in the form *major.minor*, which conforms to a version of the NGSI-LD specification | 0..1 | If provided the notification shall undergo a backwards compatibility | +| | | | | operation as defined by Clause+++clause-9+++9.5.3 and be amended to conform to the | +| | | | | supplied version of the NGSI-LD specification. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| splitEntities | Boolean | default decided by implementation; it should be configurable. The parameter does not apply in case | 0..1 | If _`true`_ it is assumed that single Entities are distributed between different | +| | | _`localOnly`_ is _`true`_ . | | Context Brokers and/or Context Sources and this has to be taken into account when a | +| | | | | applying any kind of filters (_`q`_, _`geoQ`_, _`scopeQ`_, Attributes etc.). If _`false`_ | +| | | | | it is expected that Context Broker and/or Context Source always have complete | +| | | | | Entities, which allows applying filters locally. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| subscriptionName | String | | 0..1 | A (short) name given to this Subscription. | +| | | | | | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| throttling | Number | Greater than 0. Fractional values are allowed. If _`timeInterval`_ is present it shall not appear (0 cardinality) | 0..1 | Minimal period of time in seconds which shall elapse between two consecutive notifications. | +| | | | | | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| timeInterval | Number | Greater than 0 | 0..1 | Indicates that a notification shall be delivered periodically regardless of attribute | +| | | | | changes. Actually, when the time interval (in seconds) specified in this value field | +| | | if _`watchedAttributes`_ is present it shall not appear (0 cardinality) | | is reached. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +::: + + + +At least one of (a) _`entities`_ or (b) _`watchedAttributes`_ shall be present, +unless the member _`localOnly`_ is set to _`true`,_ in which case the execution +of the request is limited to local scope (see Clause+++clause-8+++8.6). + +The members (defined by Table+++below) of the _Subscription_ data structure are +also defined. They are read-only and shall be automatically generated by NGSI-LD +implementations. They shall not be provided by Context Subscribers. In the event +that they are provided (in update or create operations) NGSI-LD implementations +shall ignore them. + + + +::: TH +Table: Additional members of the Subscription data type +::: + +::: TAL ++-------------+-------------+---------------------------+-------------+--------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+=============+===========================+=============+================================================================================+ +| status | String | Allowed values: | 0..1 | Read-only. Provided by the system when querying the details of a subscription. | +| | | ["active"]{.HTML-Code}, | | | +| | | ["paused"]{.HTML-Code}, | | | +| | | ["expired"]{.HTML-Code} | | | ++-------------+-------------+---------------------------+-------------+--------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.5.3 CSourceRegistration + +This type represents the data needed to register a new [Context +Source]{.HTML-Keyboard}. + +The supported JSON members shall follow the indications provided in +Table+++below + + + +::: TH +Table: CSourceRegistration data type definition +::: + +::: TAL ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=====================+============================================+==============================================================================================+=============+==========================================================================================================================================+ +| id | String | Valid URI. | 0..1 | Generated at creation time, if it is not provided, it will be assigned during registration process and returned to client. | +| | | | | | +| | | Unique registration identifier. (JSON-LD _`@id`_). | | It cannot be later modified in update operations. | +| | | | | | +| | | | | | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["ContextSourceRegistration"]{.HTML-Code} | 1 | JSON-LD _`@type`_ | +| | | | | | +| | | | | Use reserved type for identifying Context Source Registration. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| endpoint | String | It shall be a dereferenceable URI | 1 | Endpoint expressed as dereferenceable URI through which the [Context Source]{.HTML-Keyboard} exposes its NGSI-LD interface. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| contextSourceInfo | KeyValuePair[] | | 0..1 | Generic {key, value} array to convey optional information to provide when contacting the registered [Context Source.]{.HTML-Keyboard} | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| information | RegistrationInfo[] | See data type definition in Clause+++root.2.6.6.4 Empty array (0 length) is not allowed | 1 | Describes the Entities, Properties and Relationships for which the [Context Source]{.HTML-Keyboard} may be able to provide information. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| contextSourceAlias | String | Non-empty string. Pseudonym field as defined in IETF RFC 7230 [n.12] | 0..1 | A previously retrieved unique id for a registered [Context Source]{.HTML-Keyboard} which is used to identify loops. | +| | | | | | +| | | | | In the multi-tenancy use case (see Clause+++clause-7+++7.8), this id shall be used to **identify** a specific | +| | | | | [Tenant]{.HTML-Keyboard} within a registered [Context Source]{.HTML-Keyboard}. | +| | | | | | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| description | String | Non-empty string | 0..1 | A description of this [Context Source Registration.]{.HTML-Keyboard} | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| datasetId | String[] | Valid URIs,["@none"]{.HTML-Code} for including the default Attribute instances. | 0..1 | Specifies the datasetIds of Attributes that the [Context Source]{.HTML-Keyboard} can provide, defined as per Clause+++clause-8+++8.5. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Provides an expiration date. When passed the [Context Source Registration]{.HTML-Keyboard} will become invalid and | +| | | | | the [Context Source]{.HTML-Keyboard} might no longer be available. | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| location | GeoJSON Geometry as mandated by | | 0..1 | Location for which the [Context Source]{.HTML-Keyboard} may be able to provide information. | +| | Clause+++root.2.6.4.5 | | | | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| management | RegistrationManagementInfo | See data type definition in Clause+++root.2.6.6.5 | 0..1 | Holds additional optional registration management information that can be used to limit unnecessary distributed operation requests. | +| | | | | | +| | | | | | +| | | | | | +| | | | | | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| managementInterval | TimeInterval | See data type definition in Clause+++root.2.6.7.1 | 0..1 | If present, the [Context Source]{.HTML-Keyboard} can be queried for Temporal Entity Representations. | +| | | | | (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). | +| | | | | The _`managementInterval`_ specifies the time interval for which the [Context Source]{.HTML-Keyboard} can provide | +| | | | | Entity information as specified by the _`createdAt`_, _`modifiedAt`_ and _`deletedAt`_ Temporal Properties. | +| | | | | A temporal query based on the _`createdAt`_, _`modifiedAt`_ or _`deletedAt`_ Temporal Property is matched against | +| | | | | the _`managementInterval`_ for overlap. | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| mode | String | It shall be one of: | 0..1 | The definition of the mode of distributed operation (see Clause+++clause-9+++9) supported by | +| | | | | the registered [Context Source.]{.HTML-Keyboard} | +| | | ["inclusive","exclusive","redirect"]{.HTML-Code} or ["auxiliary"]{.HTML-Code} | | | +| | | | | | +| | | The mode is assumed to be ["inclusive"]{.HTML-Code} if not explicitly defined | | | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| observationInterval | TimeInterval | See data type definition in Clause+++root.2.6.7.1 | 0..1 | If present, the [Context Source]{.HTML-Keyboard} can be queried for Temporal Entity Representations. | +| | | | | (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). | +| | | | | The _`observationInterval`_ specifies the time interval for which the [Context Source]{.HTML-Keyboard} can provide | +| | | | | Entity information as specified by the _`observedAt`_ Temporal Property. A temporal query based on the _`observedAt`_ | +| | | | | Temporal Property, which is the default, is matched against the _`observationInterval`_ for overlap. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| observationSpace | GeoJSON Geometry as mandated by | | 0..1 | Geographic location that includes the observation spaces of all entities as specified by their respective | +| | Clause+++root.2.6.4.5 | | | _`observationSpace`_ *GeoProperty* for which the [Context Source]{.HTML-Keyboard} may be able to provide information. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| operations | String[] | Entries are limited to the named API operations and named operation groups | 0..1 | The definition limited subset of API operations supported by the registered [Context Source.]{.HTML-Keyboard} | +| | | see Clause+++clause-9+++9.2 | | | +| | | | | If undefined, the default set of operations is ["federationOps"]{.HTML-Code} (see Clause+++clause-9+++9.2). | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| operationSpace | GeoJSON Geometry as mandated by | | 0..1 | Geographic location that includes the operation spaces of all entities as specified by their respective _`operationSpace`_ *GeoProperty* | +| | Clause+++root.2.6.4.5 | | | for which the [Context Source]{.HTML-Keyboard} may be able to provide information. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| refreshRate | String | String representing a duration in ISO 8601 [n.5] format | 0..1 | An indication of the likely period of time to elapse between updates at this registered endpoint. | +| | | | | | +| | | | | Brokers may optionally use this information to help implement caching. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| registrationName | String | Non-empty string | 0..1 | A name given to this [Context Source Registration]{.HTML-Keyboard}. | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| scope | String or | Scope(s) | 0..1 | Scopes (see Clause+++root.2.7) for which the [Context Source]{.HTML-Keyboard} has Entities. | +| | | | | | +| | String[] | | | | +| | | | | | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| tenant | String | | 0..1 | Identifies the [Tenant]{.HTML-Keyboard} that has to be specified in all requests to the [Context Source]{.HTML-Keyboard} that | +| | | | | are related to the information registered in this [Context Source Registration]{.HTML-Keyboard}. If not present, the default | +| | | | | [Tenant]{.HTML-Keyboard} is assumed. Should only be present in systems supporting multi-tenancy. | ++---------------------+--------------------------------------------+----------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The members (defined by Table+++below) of the _CSourceRegistration_ data +structure are also defined. They are read-only and shall be automatically +generated by NGSI-LD implementations. In the event that they are provided (in +update or create operations) NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Additional members of the CSourceRegistration data type +::: + +::: TAL ++-------------+-------------+-----------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+=============+===================================+=============+================================================================================================================================================================================================================================================+ +| lastFailure | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp corresponding to the instant when the last distributed operation resulting in a failure (for instance, in the HTTP binding, an HTTP response code other than 2xx) was returned. | ++-------------+-------------+-----------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| status | String | Allowed values: | 0..1 | Read-only., Status of the Registration. It shall be ["ok"]{.HTML-Code} if the last attempt to perform a distributed operation succeeded. It shall be ["failed"]{.HTML-Code} if the last attempt to perform a distributed operation failed. | +| | | | | | +| | | ["ok"]{.HTML-Code} | | | +| | | | | | +| | | ["failed"]{.HTML-Code} | | | ++-------------+-------------+-----------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timesFailed | Number | 0 or greater value | 0..1 | Number of times that the registration triggered a distributed operation request that failed. | ++-------------+-------------+-----------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timesSent | Number | 0 or greater value | 0..1 | Number of times that the registration triggered a distributed operation, including failed attempts. | ++-------------+-------------+-----------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastSuccess | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp corresponding to the instant when the last successfully distributed operation was sent. Created on first successful operation. | ++-------------+-------------+-----------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.5.4 Snapshot + +This type represents the data needed to create and manage a Snapshot. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: Snapshot data type definition +::: + +::: TAL ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=========================+==================+==========================================================================================+=============+========================================================================================================================================================================================================================================================================================================+ +| id | String | Valid URI | 0..1 | System-generated at creation time, if it is not provided. It cannot be later modified in update operations. | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["Snapshot"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | +| | | | | | +| | | | | | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotQueries | Query[] | List of Query (Clause+++root.2.6.5.1), where no Query | 0..1 | Allows clients to specify a list of queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of ["snapshotQueries"]{.HTML-Code} or ["snapshotTemporalQueries"]{.HTML-Code} | +| | | has ["temporalQ"]{.HTML-Code} element. | | shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status or cloning the Snapshot. | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotTemporalQueries | Query[] | List of Query (Clause+++root.2.6.5.1), where each Query | 0..1 | Allows clients to specify a list of temporal queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of ["snapshotQueries"]{.HTML-Code} or ["snapshotTemporalQueries"]{.HTML-Code} | +| | | has ["temporalQ"]{.HTML-Code} element. | | shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status. | +| | | | | | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotLifetime | String | String representing a duration in ISO 8601 [n.5] format | 0..1 | Suggested duration for which the requester wants the Snapshot to exist with respect to the current point in time. The actual expiresAt time of the Snapshot shall be set by the NGSI-LD system, possibly overriding the requested duration. | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotPriority | Number | Positive Integer between 1 and 10 | 0..1 | The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It can be used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| endpoint | String | _Dereferenceable URI_ | 0..1 | URI to which notifications regarding changes in the status of the Snapshot are to be sent. The information contained in the receiverInfo member shall be considered. | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| receiverInfo | KeyValuePair[] | | 0..1 | Generic {key, value} array to convey optional information to the receiver. | ++-------------------------+------------------+------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_Snapshot_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by _Context +Consumers_. In the event that they are provided (in update or create operations) +NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Output only members of the Snapshot data type +::: + +::: TAL ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++================================+============================+==============================================================+=============+========================================================================================================================================================+ +| snapshotStatus | String | It shall be one of: | 1 | Allows clients to check the status of the Snapshot. | +| | | ["preparing","success","partial",]{.HTML-Code} | | | +| | | ["failure"]{.HTML-Code} | | | +| | | or ["empty"]{.HTML-Code} | | | +| | | | | | +| | | *The initial status shall be* ["preparing"]{.HTML-Code}*. | | | ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotQueriesDetails | ExecutionResultDetails[] | _List of ExecutionResultDetails_ (Clause+++root.2.6.7.5) | 0..1 | List with one result per Snapshot query execution, in the same order as Snapshot queries. | ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotTemporalQueriesDetails | ExecutionResultDetails[] | _List of ExecutionResultDetails_ (Clause+++root.2.6.7.5) | 0..1 | List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries. | ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| createdAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated creation timestamp. See Clause+++root.2.4. | ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| modifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated last modification timestamp. See Clause+++root.2.4 | ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Expiration time for the snapshot - it is possible to indirectly update the member by updating snapshotLifetime. | +| | | | | | +| | | | | See Clause+++root.2.4. | ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastUsedAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | System generated timestamp identifying the point in time when the snapshot was most recently used. It is initialized at creation time. | +| | | | | | +| | | | | See Clause+++root.2.4. | ++--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + +##### 5.2.6.5.5 EntityMap + +This type represents the data needed to define an [Entity Map]{.HTML-Keyboard} + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: EntityMap data type definition +::: + +::: TAL ++-------------+-------------+--------------------------------------------------+-------------+------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=============+=============+==================================================+=============+====================================+ +| id | String | Valid URI | 1 | EntityMap ID. | ++-------------+-------------+--------------------------------------------------+-------------+------------------------------------+ +| type | String | It shall be equal to ["EntityMap"]{.HTML-Code} | 1 | Node type. | ++-------------+-------------+--------------------------------------------------+-------------+------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Expiration date for the EntityMap. | ++-------------+-------------+--------------------------------------------------+-------------+------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_EntityMap_ data structure are also defined. They are read-only and shall be +generated by NGSI-LD implementations. They shall not be provided by [Context +Consumers]{.HTML-Keyboard}. In the event that they are provided in update +operations NGSI-LD implementations shall ignore them. + + + +::: TH +Table: Additional members of the NGSI-LD EntityMap data type +::: + +::: TAL ++-------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+=============+==================================================================================================================================================================================================================================================+=============+===============================================================================================================================+ +| entityMap | EntityMap | A set of key-value pairs whose keys shall be strings representing Entity ids and whose values shall be an array holding every CSourceRegistration id which is relevant to the ongoing Context Information Consumption request | 1 | System generated mapping of Entities to CSourceRegistrations. | +| | | (see Clause+++root.2.6.5.5). | | | +| | | | | | +| | | The key ["@none"]{.HTML-Code} shall be used to refer to an Entity that is held locally. | | | ++-------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+ +| linkedMaps | JSON | A set of key-value pairs whose keys shall be strings representing CSourceRegistration ids which are relevant to the ongoing Context Information request and whose values shall represent the associated EntityMap id used by the ContextSource. | 1 | System generated mapping of Context CSourceRegistrations to a URI indicating which EntityMaps was used by the Context Source. | ++-------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.5.6 ContextSourceIdentity + +This type represents the data uniquely identifying a [Context +Source]{.HTML-Keyboard}, and if the [Context Source]{.HTML-Keyboard} supports +multi-tenancy (see Clause+++clause-7+++7.8) uniquely identifying a +[Tenant]{.HTML-Keyboard} within that [Context Source.]{.HTML-Keyboard} + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: ContextSourceIdentity data type definition +::: + +::: TAL ++---------------------+-------------+------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=====================+=============+========================================================================+=============+================================================================================================================================================================================================================+ +| id | String | Valid URI | 1 | Context Source ID. | ++---------------------+-------------+------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["ContextSourceIdentity"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++---------------------+-------------+------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| contextSourceAlias | String | Non-empty string. Pseudonym field as defined in IETF RFC 7230 [n.12] | 1 | A unique id for a [Context Source]{.HTML-Keyboard} which can be used to identify loops. | +| | | | | In the multi-tenancy use case (see Clause+++clause-7+++7.8), this id shall be identifying a specific [Tenant]{.HTML-Keyboard} within a registered [Context Source]{.HTML-Keyboard}. | ++---------------------+-------------+------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| contextSourceUptime | String | String representing a duration in ISO 8601 [n.5] format | 1 | Total Duration that the [Context Source]{.HTML-Keyboard} has been available. | ++---------------------+-------------+------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| contextSourceTimeAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Current time observed at the [Context Source]{.HTML-Keyboard}. Timestamp See Clause+++root.2.4 | ++---------------------+-------------+------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| contextSourceExtras | JSON | | 0..1 | Instance specific information relevant to the configuration of the [Context Source]{.HTML-Keyboard} itself in raw un-expandable JSON which shall not be interpreted as JSON-LD | +| | | | | using the supplied _`@context`_. | ++---------------------+-------------+------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 5.2.6.6 Structural data types + +##### 5.2.6.6.1 Endpoint + +This datatype represents the parameters that are required in order to define an +endpoint for notifications. This can include, in addition the endpoint's URI, a +generic{key, value} array, named _receiverInfo_, which contains, in a +generalized form, whatever extra information the [Context +Broker]{.HTML-Keyboard} shall convey to the receiver in order for the [Context +Broker]{.HTML-Keyboard} to successfully communicate with receiver (e.g. +Authorization material), or for the receiver to correctly interpret the received +content (e.g. the Link URL to fetch an _`@context`_). Additionally, it can +include another generic{key, value} array, named _notifierInfo_, which contains +the configuration that the [Context Broker]{.HTML-Keyboard} needs to know in +order to correctly set up the communication channel towards the receiver (e.g. +MQTT-Version, MQTT-QoS, in case of MQTT binding, as defined in +Clause+++clause-14+++14.2). + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: Endpoint data type definition +::: + +::: TAL ++--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++==============+==================+========================================+=============+==========================================================================================================================================================================================================================================================================+ +| uri | String | Dereferenceable URI | 1 | URI which conveys the endpoint which will receive the notification. | ++--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| accept | String | MIME type. It shall be one of: | 0..1 | Intended to convey the MIME type of the notification payload body (JSON, or JSON-LD, or GeoJSON). If not present, default is ["application/json"]{.HTML-Code}. | +| | | ["application/json"]{.HTML-Code}, | | | +| | | ["application/ld+json"]{.HTML-Code}, | | | +| | | ["application/geo+json"]{.HTML-Code} | | | ++--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| cooldown | Number | Greater than 0 | 0..1 | Once a failure has occurred, minimum period of time in milliseconds which shall elapse before attempting to make a subsequent notification to the same endpoint after failure. If requests are received before the cooldown period has expired, no notification is sent. | ++--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| notifierInfo | KeyValuePair[] | | 0..1 | Generic {key, value} array to set up the communication channel. | ++--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| receiverInfo | KeyValuePair[] | | 0..1 | Generic {key, value} array to convey optional information to the receiver. | ++--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timeout | Number | Greater than 0 | 0..1 | Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed. The NGSI-LD system can override this value. This only applies if the binding protocol always returns a response. | ++--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.6.2 EntityInfo + +This type represents what Entities, Entity Types or group of Entity IDs (as a +regular expression pattern mandated by IEEE 1003.2™ [n.13]) can be provided (by +[Context Sources]{.HTML-Keyboard}). + +The supported JSON members shall follow the requirements provided in +Table+++below. _`id`_ takes precedence over _`idPattern`_. + +Notice that Cardinality of _`type`_ being 1 implies that it is not possible to +register what Entities can be provided by a [Context Source]{.HTML-Keyboard} +just by their _`id`_ or _`idPattern`_ (i.e. without specifying their _`type`_). + + + +::: TH +Table: EntityInfo data type definition +::: + +::: TAL ++-------------+----------------------+---------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+======================+=========================================================================================================+=============+============================================================================================================+ +| type | String or String[] | Fully Qualified Name of an Entity Type or the Entity Type name as a short-hand string. | 1 | Entity Type (or JSON array, in case of Entities with multiple Entity Types). | +| | | See Clause+++root.2.2.3 | | | ++-------------+----------------------+---------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ +| id | String | Valid URI | 0..1 | Entity identifier. | +| | | | | | ++-------------+----------------------+---------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ +| idPattern | String | Regular expression as per IEEE 1003.2™ [n.13] | 0..1 | A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. | +| | | | | | ++-------------+----------------------+---------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.6.3 EntitySelector + +This type selects which entity or group of entities are queried or subscribed to +by [Context Consumers]{.HTML-Keyboard}. Entities can be specified by their id, +Entity Types or group of Entity IDs (as a regular expression pattern mandated by +IEEE 1003.2™ [n.13]). + +The supported JSON members shall follow the indications provided in +Table+++below. _`id`_ takes precedence over _`idPattern`_. + + + +::: TH +Table: EntitySelector data type definition +::: + +::: TAL ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=====================+====================+============================================================================================================================+==============+================================================================================================+ +| type | String | A valid type selection string as per Clause+++clause-7+++7.2.2. To indicate a request for all Entities | 1 | Selector of Entity Type(s); If type is specified as ["\*"]{.HTML-Code}, implying local scope, | +| | | (with implied local scope), ["\*"]{.HTML-Code} is also allowed as a value. | | local scope shall not be explicitly set to be _`false`_ (Clause+++clause-8+++8.6) | +| | | | | for the execution of the corresponding operation. | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| id | String or String[] | Valid URI(s) | 0..1 | Entity identifier(s). | +| | | | | | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +| idPattern | String | Regular expression as per IEEE 1003.2™ [n.13] | 0..1 | A regular expression which denotes a pattern that shall be matched by the provided | +| | | | | or subscribed Entities. | ++---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.6.4 KeyValuePair + +This datatype represents the optional information that is required when +contacting an endpoint for notifications. + +The supported members shall follow the indications provided in Table+++below. +They are intended to represent a key/value pair. + +Example optional information includes additional HTTP Headers such as: + +- The HTTP Authentication Header. +- The HTTP Prefer Header (IETF RFC 7240 [n.14]) used when notifying the GeoJSON + Endpoint. + + + +::: TH +Table: KeyValuePair data type definition +::: + +::: TAL ++-------------+-------------+-------------------+-------------+----------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+=============+===================+=============+==================================+ +| key | String | Binding-dependent | 1 | The key of the key/value pair. | ++-------------+-------------+-------------------+-------------+----------------------------------+ +| value | String | Binding-dependent | 1 | The value of the key/value pair. | ++-------------+-------------+-------------------+-------------+----------------------------------+ +::: + + + +##### 5.2.6.6.5 RegistrationInfo + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: RegistrationInfo data type definition +::: + +::: TAL ++-------------------+----------------+----------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===================+================+==================================================================================+=============+==================================================================================+ +| entities | EntityInfo[] | See data type definition in Clause+++root.2.6.6.2 | 0..1 | Describes the entities for which the CSource may be able to provide information. | +| | | Empty array (0 length) is not allowed. | | | +| | | Restrictions in Clause+++clause-9+++9 apply as well | | | ++-------------------+----------------+----------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +| propertyNames | String[] | Property names as short hand strings or URIs. Empty array is not allowed. | 0..1 | Describes the Properties that the CSource may be able to provide. | +| | | Restrictions in Clause+++clause-9+++9 apply as well | | | ++-------------------+----------------+----------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +| relationshipNames | String[] | Relationship names as short hand strings or URIs. Empty array is not allowed. | 0..1 | Describes the Relationships that the CSource may be able to provide. | +| | | Restrictions in Clause+++clause-9+++9 apply as well | | | ++-------------------+----------------+----------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +::: + + + +At least one element of _RegistrationInfo_ shall be present. + +##### 5.2.6.6.6 RegistrationManagementInfo + +This type represents the data to alter the default behaviour of a [Context +Broker]{.HTML-Keyboard} when making a distributed operation request to a +registered [Context Source]{.HTML-Keyboard}. The supported JSON members shall +follow the indications provided in Table+++below. Brokers may override these +recommendations. + + + +::: TH +Table: RegistrationManagementInfo data type definition +::: + +::: TAL ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===============+=============+============================================================+=============+======================================================================================================================================================================================+ +| cacheDuration | String | String representing a duration in ISO 8601 [n.5] format | 0..1 | Minimal period of time which shall elapse between two consecutive context information consumption operations (as defined in Clause+++clause-10+++10.4) | +| | | | | related to the same context data will occur. | +| | | | | | +| | | | | If the _`cacheDuration`_ latency period has not been reached, a cached value for the entity or its attributes shall be returned where available. | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| cooldown | Number | Greater than 0 | 0..1 | Minimum period of time in milliseconds which shall elapse before attempting to make a subsequent forwarded request to the same endpoint after failure. | +| | | | | | +| | | | | If requests are received before the cooldown period has expired, a timeout error response for the registration is automatically returned. | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| localOnly | Boolean | | 0..1 | If _`localOnly=true`_ then distributed operations associated to this [Context Source Registration]{.HTML-Keyboard} will act only on data held directly by the registered Context | +| | | | | | +| | | | | Source itself (see Clause+++clause-9+++9.7). | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timeout | Number | Greater than 0 | 0..1 | Maximum period of time in milliseconds which may elapse before a forwarded request is assumed to have failed. | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 5.2.6.7 Parameter data types + +##### 5.2.6.7.1 TimeIntervalParams + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: TimeIntervalParams data type definition +::: + +::: TAL ++-------------+-------------+----------------------------------+-------------+-----------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+=============+==================================+=============+=============================================================================+ +| startAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Describes the start of the time interval | ++-------------+-------------+----------------------------------+-------------+-----------------------------------------------------------------------------+ +| endAt | String | _DateTime_ (Clause+++root.2.2.4) | 0 | Describes the end of the time interval. If not present the interval is open | ++-------------+-------------+----------------------------------+-------------+-----------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.7.2 GeoParams + +This datatype represents a geoquery used for Subscriptions. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: GeoParams data type definition +::: + +::: TAL ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++===============+=============+============================================================+=============+======================================================================================================================================================================================+ +| coordinates | JSON Array | A JSON Array coherent with the geometry type as | 1 | Coordinates of the reference geometry. For the sake of JSON-LD compatibility It can be encoded as a string as described in Clause+++root.2.6.4.5. | +| | or String | per IETF RFC 7946 [n.4] | | | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| geometry | String | A valid GeoJSON [n.4] geometry type excepting | 1 | Type of the reference geometry. | +| | | _GeometryCollection_ | | | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| georel | String | A valid geo-relationship as defined by | 1 | Geo-relationship (["near"]{.HTML-Code}, ["within"]{.HTML-Code}, etc.). | +| | | Clause+++clause-7+++7.2.4 | | | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| geoproperty | String | Attribute name as short hand string or URI | 0..1 | Specifies the GeoProperty to which the GeoQuery is to be applied. If not present, the default GeoProperty is _`location`_. | +| | | | | | ++---------------+-------------+------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.7.3 NotificationParams + +This datatype represents the parameters that allow to convey the details of a +notification. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: NotificationParams data type definition +::: + +::: TAL ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+=============+===============================================================================================================================================================================================================================+=============+=========================================================================================================================================================================+ +| endpoint | Endpoint | See data type definition in Clause+++root.2.6.6.1 | 1 | Notification endpoint details. | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| attributes | String[] | Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed | 0..1 | A synonym for _`pick`_, except that _`id`_, _`type`_, _`scope`_ are not allowed. **Deprecated** | +| | | | | | +| | | | | Attribute names to be included in the notification payload body. If undefined it will mean all Attributes. | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| format | String | It shall be one of: ["normalized"]{.HTML-Code}, ["concise"]{.HTML-Code}, ["simplified"]{.HTML-Code} (or its synonym ["keyValues"]{.HTML-Code}) | 0..1 | Conveys the representation format of the entities delivered at notification time. By default, it will be in the normalized format. | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| join | String | It shall be one of: ["flat"]{.HTML-Code}, ["inline"]{.HTML-Code}, ["@none"]{.HTML-Code} | 0..1 | String representing the type of [Linked Entity]{.HTML-Keyboard} retrieval to apply. | +| | | | | | +| | | | | By default, it will be ["@none"]{.HTML-Code}. | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| joinLevel | Number | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML-Keyboard} retrieval to apply. Default is 1. Only applicable if _`join`_ parameter is ["flat"]{.HTML-Code}, or ["inline"]{.HTML-Code}. | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| omit | String[] | Entity member (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or a projected Attribute name) as a valid attribute projection language string as per Clause+++clause-7+++7.3.2. | 0..1 | When defined, the specified Entity members are removed from each Entity within the payload. | +| | | Empty array (0 length) is not allowed | | | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| pick | String[] | Entity member (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or a projected Attribute name as a valid attribute projection language string as per Clause+++clause-7+++7.3.2. | 0..1 | When defined, every Entity within the payload body is reduced down to only contain the specified Entity members. | +| | | Empty array (0 length) is not allowed | | | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| showChanges | Boolean | _`false`_ by default | 0..1 | If _`true`_ the previous _`value`_ (_`previousValue`_) of Properties or _`languageMap`_ (_`previousLanguageMap`_) of Language Properties or | +| | | | | _`object`_ (_`previousObject`_) of Relationships is provided in addition to the current one. This requires that it exists, i.e. in case of | +| | | | | modifications and deletions, but not in the case of creations. | +| | | | | | +| | | | | _`showChanges`_ cannot be _`true`_ in case format is ["keyValues"]{.HTML-Code}. | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| sysAttrs | Boolean | _`false`_ by default | 0..1 | If _`true`_, the system generated attributes _`createdAt`_ and _`modifiedAt`_ and the system attribute _`expiresAt`_ are included in the response payload body, | +| | | | | in the case of a deletion also _`deletedAt`_. | +| | | | | | ++-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +The following **output only** members (defined by Table+++below) of the +_NotificationParams_ data structure are also defined. They are read-only and +shall be automatically generated by NGSI-LD implementations. They shall not be +provided by _Context Subscribers_. In the event that they are provided (in +update or create operations) NGSI-LD implementations shall ignore them. + +In query or retrieve operations involving Subscriptions, implementations shall +generate them as part of their representation. + + + +::: TH +Table: Output only members of the NotificationParams data structure +::: + +::: TAL ++------------------+-------------+------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++==================+=============+================================================+=============+=========================================================================================================================================================================================================================================================+ +| lastFailure | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp corresponding to the instant when the last notification resulting in failure (for instance, in the HTTP binding, an HTTP response code different than 200) has been sent. Provided by the system when querying the details of a subscription. | ++------------------+-------------+------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastNotification | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp corresponding to the instant when the last notification has been sent. Provided by the system when querying the details of a subscription. | ++------------------+-------------+------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastSuccess | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Timestamp corresponding to the instant when the last successful (200 OK response) notification has been sent. Provided by the system when querying the details of a subscription. | ++------------------+-------------+------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| status | String | Allowed values: | 0..1 | Status of the Notification. It shall be ["ok"]{.HTML-Code} if the last attempt to notify the subscriber succeeded. It shall be ["failed"]{.HTML-Code} if the last attempt to notify the subscriber failed. | +| | | | | | +| | | ["ok"]{.HTML-Code}, ["failed"]{.HTML-Code} | | | ++------------------+-------------+------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timesFailed | Number | Greater than 0 | 0..1 | Number of times an unsuccessful response (or timeout) has been received when delivering the notification. Provided by the system when querying the details of a subscription. | ++------------------+-------------+------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timesSent | Number | Greater than 0 | 0..1 | Number of times that the notification has been sent. Provided by the system when querying the details of a subscription. | ++------------------+-------------+------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.7.4 TemporalParams + +This datatype represents a temporal query. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: TemporalParams data type definition +::: + +::: TAL ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++====================+=========================================================================+==========================================================================================================================================================================================================================+=============+==========================================================================================================================================================================================================================================================+ +| timeAt | String representing the _`timeAt`_ parameter as defined by | It shall be a _DateTime_ | 1 | | +| | Clause+++clause-7+++7.2.6 | | | | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timerel | String | Allowed values: ["before"]{.HTML-Code}, ["after"]{.HTML-Code} and ["between"]{.HTML-Code} | 1 | Represents the temporal relationship as defined by Clause+++clause-7+++7.2.6 | +| | | | | | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| aggrMethods | Comma separated list of string | It shall be 1 if _`aggregatedValues`_ is present in the _`options`_ parameter | 0..1 | Each String represents an aggregation method, as defined by Clause+++root.3.2.7. Only applicable if ["aggregatedValues"]{.HTML-Code} is present in the _`format`_ or _`options`_ parameter. | +| | | | | | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| aggrPeriodDuration | String | | 0..1 | It represents the duration of each period used for the aggregation as defined by Clause+++root.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. | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| endTimeAt | String representing the _`endTimeAt`_ parameter as defined by | It shall be a _DateTime_. Cardinality shall be 1 if _`timerel`_ is equal to ["between"]{.HTML-Code} | 0..1 | | +| | Clause+++clause-7+++7.2.6 | | | | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastN | Positive integer | | 0..1 | Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| timeproperty | String representing a Temporal Property name | Allowed values: ["observedAt"]{.HTML-Code}, ["createdAt"]{.HTML-Code}, ["modifiedAt"]{.HTML-Code} and ["deletedAt"]{.HTML-Code}. If not specified, the default is ["observedAt"]{.HTML-Code}. (See Clause+++root.2.4) | 0..1 | | +| | | | | Only applicable if ["aggregatedValues"]{.HTML-Code} is present in the _`format`_ or _`options`_ parameter. | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.7.5 OrderingParams + +This datatype represents the parameters that convey the definition used whilst +ordering Entities. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: OrderingParams data type definition +::: + +::: TAL ++-------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=============+=============+===================================================================================================================================================================================================================================================================================================+=====================================================+=============================================================================================================================================================================+ +| collation | String | An ICU collation (see IETF RFC 6067 [n.15]). | 0..1 | The Entities returned in the payload shall be ordered according to the collation given. By default, it shall be ICU "root" collation order (["und-x-icu"]{.HTML-Code}). | ++-------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| coordinates | JSON Array | A JSON Array coherent with the geometry type as per IETF RFC 7946 [n.4]. | 0..1 | Coordinates of a Geometry used when sorting by distance. | +| | | | | | +| | | | It shall be one if _`orderBy`_ | | +| | | | uses order by distance | | ++-------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| geometry | String | A valid GeoJSON [n.4] geometry type excepting _GeometryCollection_. | 0..1 | The type of geometry whose coordinates are used when sorting by distance. By default, it shall be a ["Point"]{.HTML-Code} geometry. | ++-------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| orderBy | String[] | Each String is an Entity member (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or an Attribute name) appended with an optional sorting style (["asc"]{.HTML-Code}, ["desc"]{.HTML-Code}, ["dist-asc"]{.HTML-Code}, ["dist-desc")]{.HTML-Code} as per Clause+++clause-7+++7.6.2. | 1 | When defined, the Entities returned in the payload shall be ordered according to members defined. | ++-------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.7.6 AggregationParams + +This datatype represents the parameters required for supporting aggregation +methods in temporal requests. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: AggregationParams data type definition +::: + +::: TAL ++--------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++====================+=================================+==========================================================================================================================================================+=============+=============+ +| aggrMethods | Comma separated list of strings | Each String represents an aggregation method, as defined by Clause+++root.3.2.7. | 1 | \- | ++--------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+ +| aggrPeriodDuration | String | It represents the duration of each period used for the aggregation as defined by Clause+++root.3.2.7 | 0..1 | \- | +| | | | | | +| | | If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query. | | | ++--------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+ +::: + + + +#### 5.2.6.8 Results and errors data types + +##### 5.2.6.8.1 OperationResult + +This datatype represents the result of a batch or distributed operation. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: OperationResult data type definition +::: + +::: TAL ++-------------+----------------------+---------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+======================+=====================+=============+==================================================================================================================================================================+ +| errors | BatchEntityError[] | | 1 | One array item per Element in error. Empty Array if no errors happened. | ++-------------+----------------------+---------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| success | String[] | Array of valid URIs | 1 | Array of Entity IDs corresponding to the Elements that were successfully treated by the concerned operation. Empty Array if no Element was successfully treated. | ++-------------+----------------------+---------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.8.2 EntityError + +This datatype represents an error raised (associated to a particular Entity) +during the execution of a batch or distributed operation. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: EntityError data type definition +::: + +::: TAL ++----------------+---------------------------------------------+--------------+-------------+-----------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++================+=============================================+==============+=============+=============================================================================+ +| entityId | String | Valid URI | 1 | Entity ID corresponding to the Entity in error. | ++----------------+---------------------------------------------+--------------+-------------+-----------------------------------------------------------------------------+ +| error | ProblemDetails (see IETF RFC 7807 [n.6]) | | 1 | One instance per Entity in error. | ++----------------+---------------------------------------------+--------------+-------------+-----------------------------------------------------------------------------+ +| registrationId | String | Valid URI | 0..1 | Registration Id corresponding to a failed distributed operation (optional). | ++----------------+---------------------------------------------+--------------+-------------+-----------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.8.3 ExecutionResult + +This type represents the details of the result of execution a request, e.g. a +Query. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: ExecutionResult data type definition +::: + +::: TAL ++----------------+-------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++================+=============+=============================================+=============+========================================================================================================================================================================================+ +| problemDetails | JSON | ProblemDetails (see IETF RFC 7807 [n.6]) | 0..1 | Provides more details regarding the result status, especially when reporting an error. | ++----------------+-------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| resultStatus | String | It shall be one of: | 1 | Describes the status of the result. ["failure"]{.HTML-Code}, if an error is reported, ["success"]{.HTML-Code} in case of a non-empty result and ["empty"]{.HTML-Code} otherwise. | +| | | ["success"]{.HTML-Code}, | | | +| | | ["failure"]{.HTML-Code}, | | | +| | | or ["empty"]{.HTML-Code} | | | ++----------------+-------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.8.4 NotUpdatedResult + +This datatype represents additional information provided by an implementation +when an Attribute update did not happen. See also Clause+++root.2.6.8.5. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: NotUpdatedResult data type definition +::: + +::: TAL ++----------------+-------------+--------------+-------------+-----------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++================+=============+==============+=============+=============================================================================+ +| attributeName | String | | 1 | Attribute name. | ++----------------+-------------+--------------+-------------+-----------------------------------------------------------------------------+ +| reason | String | | 1 | Reason for not having changed such Attribute. | ++----------------+-------------+--------------+-------------+-----------------------------------------------------------------------------+ +| registrationId | String | Valid URI | 0..1 | Registration Id corresponding to a failed distributed operation (optional). | ++----------------+-------------+--------------+-------------+-----------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.8.5 UpdateResult + +This datatype represents the result of Attribute update (append or update) +operations in the NGSI-LD API regardless of whether local or distributed. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: UpdateResult data type definition +::: + +::: TAL ++-------------+-----------------------+----------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++=============+=======================+============================+=============+=======================================================================================================================================+ +| notUpdated | NotUpdatedDetails[] | See Clause+++root.2.6.8.4 | 1 | List which contains the Attributes (represented by their name) that were not updated, together with the reason for not being updated. | ++-------------+-----------------------+----------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| updated | String[] | | 1 | List of Attributes (represented by their name) that were appended or updated. | ++-------------+-----------------------+----------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +#### 5.2.6.9 Notificational data types + +##### 5.2.6.9.1 Notification + +This datatype represents the parameters that allow building a notification to be +sent to a subscriber. How to build this notification is detailed in +Clause+++clause-10+++10.5.7 + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: Notification data type definition +::: + +::: TAL ++----------------+-----------------------------------------+-----------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++================+=========================================+=====================================================+=============+======================================================================================================+ +| id | String | Valid URI | 1 | Notification identifier (JSON-LD _`@id`_). It shall be automatically generated by the implementation.| ++----------------+-----------------------------------------+-----------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["Notification"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++----------------+-----------------------------------------+-----------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------+ +| data | NGSI-LD Entity[] or FeatureCollection | | 1 | The content of the notification as NGSI-LD Entities. See Clause+++root.2.6.4.1. | +| | | | | | +| | | | | If the notification has been triggered from a Subscription that has the _`notification.`_ | +| | | | | _`endpoint.accept`_ field set to [application/geo+json]{.HTML-Code} then [data]{.HTML-Sample} | +| | | | | is returned as a _FeatureCollection_. In this case, if the _`notification.endpoint.receiverInfo`_ | +| | | | | contains the key ["Prefer"]{.HTML-Code} and it is set to the value ["body=json"]{.HTML-Code}, | +| | | | | then the _FeatureCollection_ will not contain an _`@context`_ field. | +| | | | | | +| | | | | | +| | | | | If _`endpoint.accept`_ is not set or holds another value then Entity[] is returned. | ++----------------+-----------------------------------------+-----------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------+ +| notifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Timestamp corresponding to the instant when the notification was generated by the system. | ++----------------+-----------------------------------------+-----------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------+ +| subscriptionId | String | Valid URI | 1 | Identifier of the subscription that originated the notification. | ++----------------+-----------------------------------------+-----------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.9.2 CSourceNotification + +This datatype represents the parameters that allow building a [Context +Source]{.HTML-Keyboard} Notification to be sent to a subscriber. How to build +this notification is detailed in Clause+++clause-12+++12.4.7. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: CSourceNotification data type definition +::: + +::: TAL ++----------------+------------------+------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++================+==================+==================================================================+=============+=============================================================================================================================================================================================+ +| id | String | Valid URI | 1 | CSource notification identifier (JSON-LD _`@id`_). | ++----------------+------------------+------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["ContextSourceNotification"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++----------------+------------------+------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data | CSource | | 1 | The content of the notification as NGSI-LD CSourceRegistrations. See Clause+++root.2.6.5.3. | +| | | | | | +| | Registration[] | | | | ++----------------+------------------+------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| notifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Timestamp corresponding to the instant when the notification was generated by the system. | ++----------------+------------------+------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| subscriptionId | String | Valid URI | 1 | Identifier of the subscription that originated the notification. | ++----------------+------------------+------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| triggerReason | String | _TriggerReasonEnumeration_ (Clause+++root.2.6.9.4) | 1 | Indicates whether the CSources in the CSourceRegistration(s) in data are newly matching (initial notification or creation), have been updated (but still match) or do not match any longer. | ++----------------+------------------+------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.9.3 SnapshotNotification + +This datatype represents the parameters that allow building a snapshot +notification to be sent to a subscriber. How to build this notification is +detailed in Clause+++clause-16+++16.8. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: SnapshotNotification data type definition +::: + +::: TAL ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restrictions | Cardinality | Description | ++================================+============================+=============================================================+=============+=============================================================================================================================================================================================================================+ +| Id | String | Valid URI | 1 | Notification identifier (JSON-LD _`@id`_). It shall be automatically generated by the implementation. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["SnapshotNotification"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Expiration time for the snapshot - if expiresAt is before notifiedAt, the notification indicates that the snapshot has been deleted. In this case, snapshotReady shall be set to _`false`_. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| notifiedAt | String | _DateTime_ (Clause+++root.2.2.4) | 1 | Timestamp corresponding to the instant when the notification was generated by the system. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotId | String | Valid URI | 1 | Identifier of the snapshot whose status change triggered the notification. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotPriority | Number | Positive Integer between 1 and 10 | 1 | The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It is used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotQueriesDetails | ExecutionResultDetails[] | _List of ExecutionResultDetails_ (Clause+++root.2.6.8.3) | 0..1 | List with one result per Snapshot query execution, in the same order as Snapshot queries. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| snapshotStatus | String | It shall be one of: | 1 | Indicates the status of the Snapshot, enabling the user to decide whether the snapshot is ready for querying. | +| | | ["success"]{.HTML-Code}, | | | +| | | ["partial"]{.HTML-Code}, | | | +| | | ["failure"]{.HTML-Code} | | | +| | | or ["empty"]{.HTML-Code} | | | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| temporalSnapshotQueriesDetails | ExecutionResultDetails[] | _List of ExecutionResultDetails_ (Clause+++root.2.6.8.3) | 0..1 | List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries. | ++--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.9.4 TriggerReasonEnumeration + +The enumeration can take one of the following values: + +- ["newlyMatching"]{.HTML-Code} - describes the case that the notified [Context + Source Registration]{.HTML-Keyboard}(s) newly match(es) the identified + subscription. This value is used in the first notification and whenever a new + [Context Source Registration]{.HTML-Keyboard} matching the Subscription has + been registered, or an existing [Context Source Registration]{.HTML-Keyboard} + that did not match before has been updated in such a way that it matches now. +- ["updated"]{.HTML-Code} - describes the case that the notified [Context Source + Registration]{.HTML-Keyboard} that was part of a previous notification has + been updated, but still matches the Subscription. +- ["noLongerMatching"]{.HTML-Code} - describes the case that the notified + [Context Source Registration]{.HTML-Keyboard} that was part of a previous + notification no longer matches the Subscription, i.e. as a result of an update + or because it was deleted. + +#### 5.2.6.10 Availability data types + +##### 5.2.6.10.1 Attribute + +This type represents the data needed to define the attribute information needed +as: + +- part of the entity type information representation as mandated by + Clause+++root.2.6.10.4; +- the detailed attribute list representation; +- the attribute information representation. + +The supported JSON members shall follow the requirements provided in +Table+++below. + +The attribute list representation is used to consume information about +attributes whereas the detailed attribute list representation is used to consume +detailed information about attributes including the names of entity types that +have instances with attributes, which have the respective attribute name. + + + +::: TH +Table: Attribute data type definition +::: + +::: TAL ++----------------+-------------+--------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++================+=============+==================================================+=============+=======================================================================================================================================================+ +| id | String | Valid URI | 1 | Full URI of attribute name. | ++----------------+-------------+--------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["Attribute"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++----------------+-------------+--------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| attributeName | String | | 1 | Name of the attribute, short name if contained in _`@context`_. | ++----------------+-------------+--------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| attributeCount | Number | Unsigned integer | 0..1 | Number of attribute instances with this attribute name. | ++----------------+-------------+--------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| attributeTypes | String[] | | 0..1 | List of attribute types (e.g. _Property_, _Relationship_, _GeoProperty_) for which entity instances exist, which contain an attribute with this name. | ++----------------+-------------+--------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| typeNames | String[] | | 0..1 | List of entity type names for which entity instances exist containing attributes that have the respective name. | ++----------------+-------------+--------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.10.2 AttributeList + +This type represents the data needed to define the attribute list +representation. The attribute list representation is used to consume information +about attributes. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: AttributeList data type definition +::: + +::: TAL ++---------------+-------------+------------------------------------------------------+-------------+--------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++===============+=============+======================================================+=============+================================================================================+ +| id | String | Valid URI | 1 | URI that is unique within the system scope. Identifier for the attribute list. | ++---------------+-------------+------------------------------------------------------+-------------+--------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["AttributeList"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++---------------+-------------+------------------------------------------------------+-------------+--------------------------------------------------------------------------------+ +| attributeList | String[] | | 1 | List containing the attribute names. | ++---------------+-------------+------------------------------------------------------+-------------+--------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.10.3 EntityType + +This type represents the data needed to define the elements of the detailed +entity type list representation. The detailed entity type list representation is +used to consume detailed information about entity types including the names of +attributes that instances of each entity type can have. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: EntityType data type definition +::: + +::: TAL ++----------------+-------------+---------------------------------------------------+-------------+-------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++================+=============+===================================================+=============+=====================================================================================+ +| id | String | Valid URI | 1 | Fully Qualified Name (FQN) of the entity type being described. | ++----------------+-------------+---------------------------------------------------+-------------+-------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["EntityType"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++----------------+-------------+---------------------------------------------------+-------------+-------------------------------------------------------------------------------------+ +| attributeNames | String[] | | 1 | List containing the names of attributes that instances of the entity type can have. | ++----------------+-------------+---------------------------------------------------+-------------+-------------------------------------------------------------------------------------+ +| typeName | String | | 1 | Name of the entity type, short name if contained in _`@context`_. | ++----------------+-------------+---------------------------------------------------+-------------+-------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.10.4 EntityTypeInfo + +This type represents the data needed to define the detailed entity type +information representation. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: EntityTypeInfo data type definition +::: + +::: TAL ++------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++==================+===============+================================================================================================================================================================================================+=============+===================================================================================+ +| id | String | Valid URI | 1 | Fully Qualified Name (FQN) of the entity type being described. | ++------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["EntityTypeInfo"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------+ +| attributeDetails | Attribute[] | See data type definition in Clause+++root.2.6.10.1. Attribute with only the elements ["id"]{.HTML-Code}, ["type"]{.HTML-Code}, ["attributeName"]{.HTML-Code} | 1 | List of attributes that entity instances with the specified entity type can have. | +| | | and ["attributeTypes"]{.HTML-Code} | | | ++------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------+ +| entityCount | Number | Unsigned integer | 1 | Number of entity instances of this entity type. | ++------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------+ +| typeName | String | | 1 | Name of the entity type, short name if contained in _`@context`_. | ++------------------+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.10.5 EntityTypeList + +This type represents the data needed to define the entity type list +representation. The entity type list representation is used to consume +information about entity types. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: EntityTypeList data type definition +::: + +::: TAL ++-------------+-------------+-------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=============+=============+=======================================================+=============+==================================================================================+ +| id | String | Valid URI | 1 | URI that is unique within the system scope. Identifier for the entity type list. | ++-------------+-------------+-------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["EntityTypeList"]{.HTML-Code} | 1 | JSON-LD _`@type`_. | ++-------------+-------------+-------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +| typeList | String[] | | 1 | List containing the entity type names. | ++-------------+-------------+-------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ +::: + + + +#### 5.2.6.11 Geographical data types + +##### 5.2.6.11.1 Feature + +This data type represents a spatially bounded Entity in GeoJSON format, as +mandated by IETF RFC 7946 [n.4]. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: Feature data type definition +::: + +::: TAL ++-------------+---------------------------------+-------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=============+=================================+===========================================================================================+=============+=================================================================================================================================+ +| id | String | Valid URI | 1 | Entity ID. | ++-------------+---------------------------------+-------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| type | String | It shall be equal to ["Feature"]{.HTML-Code} | 1 | GeoJSON Type. | ++-------------+---------------------------------+-------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| geometry | GeoJSON Object | The value field from the matching _GeoProperty_ (as specified in Clause+++root.3.3) | 1 | _`null`_ if no matching _GeoProperty_. | +| | | or _`null`_ | | | ++-------------+---------------------------------+-------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| properties | FeatureProperties | See data type definition | 1 | List of attributes as mandated by Clause+++root.2.6.11.3. | ++-------------+---------------------------------+-------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| \@context | URI, JSON Object, or JSON Array | See [n.8], section 5.1. | 0..1 | JSON-LD _`@context`_. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [n.14]). | ++-------------+---------------------------------+-------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.11.2 FeatureCollection + +This data type represents a list of spatially bounded Entities in GeoJSON +format, as mandated by IETF RFC 7946 [n.4]. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: FeatureCollection data type definition +::: + +::: TAL ++-------------+---------------------------------+----------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=============+=================================+==========================================================+=============+=================================================================================================================================+ +| type | String | It shall be equal to ["FeatureCollection"]{.HTML-Code} | 1 | GeoJSON Type. | ++-------------+---------------------------------+----------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| features | Feature[] | See data type definition | 1..N | In the case that no matches are found, _`features`_ will be an empty array. | ++-------------+---------------------------------+----------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +| \@context | URI, JSON Object, or JSON Array | See [n.8], section 5.1. | 0..1 | JSON-LD _`@context`_. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [n.14]). | ++-------------+---------------------------------+----------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +##### 5.2.6.11.3 FeatureProperties + +This data type represents the type and the associated attributes (_Properties_ +and _Relationships_) of an Entity in GeoJSON format. + +The supported JSON members shall follow the requirements provided in +Table+++below. + + + +::: TH +Table: FeatureProperties data type definition +::: + +::: TAL ++-------------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Restriction | Cardinality | Description | ++=====================================+=======================================================+==========================================+==================================+===========================================================================================================+ +| type | String or String[] | Entity Type | 1 | Entity Type (or JSON array, in case of Entities with multiple Entity Types). | +| | | | | Both short hand string (type name) or URI are allowed. | ++-------------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] \ | See datatype definition | 0..N | Properties of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.3 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] \ | See datatype definition | 0..N | GeoProperties of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.5 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] \ | See datatype definition | 0..N | LanguageProperties of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.6 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] \ | See datatype definition | 0..N | JsonProperties of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.10 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] \ | See datatype definition | 0..N | VocabProperties of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.7 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] \ | See datatype definition | 0..N | ListProperties of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.8 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Relationship or Relationship[] \ | See datatype definition | 0..N | Relationships of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.4 | | | +| +-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] \ | See datatype definition | 0..N | ListRelationships of the Entity. | +| | (see note 1) | in Clause+++root.2.6.4.9 | | | ++-------------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| For each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, there can be one or more instances separated by _`datasetId`_. | +| | +| >>> | +| | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +### 5.2.7 Scopes + +An NGSI-LD Scope enables putting Entities into a hierarchical structure and +restrict results of queries and notifications accordingly. The hierarchical +structure is user-defined, e.g. according to (logical) location or organization. +The use of Scopes is optional and an Entity can be assigned to one or more +Scopes at the same time. The Scope is represented as a special _`scope`_ +Property that is non-reified in the normalized Entity representation and reified +in the temporal representation of an Entity. In the latter case, it is +restricted to having the non-reified Temporal Properties _`createdAt`_, +_`modifiedAt`_ and _`deletedAt`_ as sub-Properties. There shall at most be one +instance of the _`scope`_ property per Entity. In case multiple representations +of the same Entity have to be merged, e.g. when combining the results of +distributed queries, the values of _`scope`_ are merged. The value of _`scope`_ +is represented as a JSON array in case there is more than one Scope. For the +Temporal Evolution a given Scope is considered valid from the time it has been +set until the time it has been explicitly removed by an update or delete +operation (for an example see Annex A, Clause+++annex-c+++A.15). + +The grammar that encodes the syntax of the Scope is expressed in ABNF format +[n.16]. It is described below (it has been validated using +[),]{.Hyperlink} and it shall be supported by +implementations. The special string ["urn:ngsi-ld:null"]{.HTML-Code} (i.e. the +NGSI-LD Null) shall be only used and only appear in case of deleted scopes. + + + +```text +Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel) ; [/] ScopeLevel *(/ScopeLevel) +Scope =/ "urn:ngsi-ld:null" ; the literal string "urn:ngsi-ld:null" +ScopeLevel = unicodeLetter *ScopeLevelChar +ScopeLevelChar = unicodeNumber / unicodeLetter +ScopeLevelChar =/ %x5F ; _ +``` + + + + + +>>> [!tip] EXAMPLE 1: + +[/Madrid]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +[Madrid]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +[/Madrid/Gardens/ParqueNorte]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 4: + +[/CompanyA/OrganizationB/UnitC]{.HTML-Code} + +>>> + + + +## 5.3 Representations in the different formats + +### 5.3.1 Introduction + +This clause defines the representation of Entity data. Implementations shall be +able to represent Entity data using multiple media types (JSON-LD, GeoJSON). The +Attributes of an Entity can be returned in three different formats +(**normalised**, **concise**, **simplified**). When representing the [Temporal +Evolution of an Entity]{.HTML-Keyboard}, three additional attribute formats are +defined (**normalised**, **simplified**, **aggregated**). + +Unless otherwise specified, the default representation of an Entity shall use +JSON-LD and Attributes in the **normalised** format. + +### 5.3.2 JSON-LD + +#### 5.3.2.1 Core and User \@context + +NGSI-LD serialization is based on JSON-LD [n.8], a JSON-based format to +serialize Linked Data. The _`@context`_ in JSON-LD is used to expand terms, +provided as short-hand strings, to concepts, specified as URIs, and vice versa, +to compact URIs into terms. The Core NGSI-LD (JSON-LD) _`@context`_ is defined +as a JSON-LD _`@context`_ which contains: + +- The core terms needed to uniquely represent the key concepts defined by the + NGSI-LD Information Model, as mandated by Clause+++clause-8+++8.2.4. +- The terms needed to uniquely represent all the members that define the + API-related Data Types, as mandated by Clause+++root.2.6. +- A fallback _`@vocab`_ rule to expand or compact user-defined terms to a + default URI, in case there is no other possible expansion or compaction as per + the current _`@context`_. +- The core NGSI-LD _`@context`_ defines the term ["id"]{.HTML-Code}, which is + mapped to _`@id`_, and the term ["type"]{.HTML-Code}, which is mapped to + _`@type`_. Since _`@id`_ and _`@type`_ are what is typically used in JSON-LD, + they may also be used in NGSI-LD requests instead of ["id"]{.HTML-Code} and + ["type" ]{.HTML-Code} respectively, wherever this is applicable. In NGSI-LD + responses, only ["id"]{.HTML-Code} and ["type"]{.HTML-Code} shall be used. + +NGSI-LD compliant implementations shall support such Core _`@context`_, which +shall be implicitly present when processing or generating context information. +Furthermore, the Core _`@context`_ is protected and shall remain immutable and +invariant during expansion or compaction of terms. Therefore, and as per the +JSON-LD processing rules [n.8], when processing NGSI-LD content, implementations +shall consider the Core _`@context`_ as if it were in the **last** position of +the _`@context`_ array. Nonetheless, for the sake of compatibility and +cleanness, data providers should generate JSON-LD content that conveys the Core +_`@context`_ in the last position. + +For the avoidance of doubt, when rendering NGSI-LD Elements, the Core +_`@context`_ **shall always be treated** as if it had been originally placed +**in the last position**, so that, if needed, upstream JSON-LD processors can +properly expand as NGSI-LD or override the resulting JSON-LD documents provided +by API implementations. + +The NGSI-LD Core _`@context`_ is publicly available at +`` and shall +contain all the terms as mandated by Annex B. + +In addition to the terms defined by the Core NGSI-LD _`@context`_ (mandatory as +per Annex B), a user _`@context`_ should be provided and it should contain the +following terms: + +- One term associated to the Entity Type, mapping the Entity Type name with its + Type Identifier (URI). +- One term associated to the name of each _Attribute_ or any of its subclasses + mapping the Property name with its Property Identifier (URI). + +Whereas the Core NGSI-LD _`@context`_ contains JSON-LD Scoped Contexts, the user +_`@context`_ shall not contain JSON-LD Scoped Contexts (see [n.8], +Clause+++root.3.2.1), as described in Clause+++clause-8+++8.2.4, because this +would enable overwriting terms defined in the Core NGSI-LD _`@context`_. + +Depending on the binding, the _`@context`_ may not just be provided embedded +with the rest of the JSON content, but there could be other options. For +example, in the HTTP binding, the _`@context`_ can be made available through a +Link header (see Clause+++clause-6+++6.2.4). + +#### 5.3.2.2 Entities Normalized + +An NGSI-LD Entity shall be represented by an object encoded using JSON-LD [n.8]. +The rules described below state the default encoding (known as the **normalized +format**) that shall be supported by implementations. Annex D provides a +computational description of this process in terms of an algorithm. + +The JSON-LD object that contains the following members: + +**Mandatory** + +- ["id"]{.HTML-Code} whose value shall be a URI that identifies the Entity. +- ["type"]{.HTML-Code} whose value shall be equal to the Entity Type name or an + unordered JSON array with multiple Entity Type names in case of an Entity that + has multiple Entity Types. + +**Optional** + +- ["expiresAt"]{.HTML-Code}: a string as mandated by Clause+++root.2.4. +- ["scope"]{.HTML-Code} whose value shall be a Scope as defined in + Clause+++root.2.7 or an unordered JSON array with multiple Scopes in case of + an Entity that has multiple Scopes. +- ["@context"]{.HTML-Code} a JSON-LD _`@context`_ as described in + Clause+++root.3.2.1. +- One member for each _Attribute_ (each _Property_, _Relationship_, or + subclasses thereof) as per the rules stated in Clause+++root.2.6.4. In case of + multiple _Attribute_ instances with the same Property name as described in + Clause+++clause-8+++8.5, all instances are provided as an unordered JSON + array, and _`datasetId`_ (see Clause+++clause-8+++8.5) shall be used to + distinguish them. + +Terms defined in the Core Context as non-reified Properties (such as +["datasetId"]{.HTML-Code}, ["instanceId"]{.HTML-Code}, etc.) shall not be used +as Attribute names. + +**Attributes of an Entity** + +Each _Attribute_ in normalized format shall be represented by a member whose key +is the Attribute name (a term) and whose value is a JSON-LD object (or JSON-LD +array with such JSON-LD objects, if there are multiple instances with the same +Attribute name, as described in Clause+++clause-8+++8.5), which includes the +following members: + +**Mandatory** + +For Each _Attribute_, one of the following members shall be present: + +- ["value"]{.HTML-Code} indicating a _Property_ - further members shall follow + the data type described in Clause+++root.2.6.4.3 +- ["object"]{.HTML-Code} indicating a _Relationship_ - further members shall + follow the data type described in Clause+++root.2.6.4.4 +- ["value"]{.HTML-Code} indicating a _GeoProperty_ - further members shall + follow the data type described in Clause+++root.2.6.4.5 +- ["languageMap"]{.HTML-Code} indicating a _LanguageProperty_ - further members + shall follow the data type described in Clause+++root.2.6.4.6 +- ["vocab"]{.HTML-Code} indicating a _VocabProperty_ - further members shall + follow the data type described in Clause+++root.2.6.4.7 +- ["valueList"]{.HTML-Code} indicating a _ListProperty_ - further members shall + follow the data type described in Clause+++root.2.6.4.8 +- ["objectList"]{.HTML-Code} indicating a _ListRelationship_ - further members + shall follow the data type described in Clause+++root.2.6.4.9 +- ["json"]{.HTML-Code} indicating a _JsonProperty_ - further members shall + follow the data type described in Clause+++root.2.6.4.10 + +On an _Attribute_, the following member is also mandatory, aligning with the +data type described above: + +- ["type"]{.HTML-Code}: a fixed value describing the Attribute data type, one of + the following values: + - ["Property"]{.HTML-Code}, ["Relationship"]{.HTML-Code}, + ["GeoProperty"]{.HTML-Code}, ["LanguageProperty"]{.HTML-Code}, + ["VocabProperty"]{.HTML-Code}, ["ListProperty"]{.HTML-Code}, + ["ListRelationship"]{.HTML-Code}, ["JsonProperty"]{.HTML-Code} + +_Attributes_ shall not contain any embedded _`@context`_, as described in +Clause+++clause-8+++8.2.4. + + + +>>> [!note] NOTE: + + +An NGSI-LD Null (explained in Clause+++root.3.1 and defined in +Clause 3.1) can be used as the right-hand side of the member +described above during partial update patch and merge patch (see +Clause+++clause-8+++8.4.2 and Clause+++clause-8+++8.4.3) to indicate a deletion +of the _Attribute_, as well as in notifications and in temporal evolutions (for +encoding a deleted _Attribute_). + +>>> + + + +It should be noted that in the JSON-LD serialization, a **number** data type +does not allow for leading zeros, and octal and hexadecimal formats are not +used. In the [Context Broker's]{.HTML-Keyboard} internal representation, a +**number** is equivalent to either an integer or floating-point number, +depending on if the number has a non-zero fractional part. The degree of +precision of a floating-point number held within a [Context +Broker]{.HTML-Keyboard} will depend upon the implementation, and insignificant +digits may be lost during the deserialization and serialization process. + +#### 5.3.2.3 Entities Concise + +_Attributes_, their values and their sub-attributes can be represented in two +equally valid lossless formats. The **normalized format** is a JSON-LD document +that is complete with respect to mandatory members. The **concise format** is a +terser JSON-LD alternative, which makes various implicit assumptions against the +payloads and removes redundancy from them. + +Although normalized format is to be considered as the default, both normalized +and concise lossless formats of Attributes shall be supported by implementations +and can be selected by [Context Consumers]{.HTML-Keyboard} through specific +request parameters. An example of this representation can be found in Annex C, +Clause+++annex-c+++C.2.2 + +**Normalized-to-Concise Compaction** + +The compaction algorithm for normalized-to-concise can be achieved in the +following steps. + +For Each _Attribute_: + +1. Every Attribute is formed as a key-value pair, the key (left-hand-side) + being the Attribute Name and the value (right hand side) being a JSON + object. In the multi-attribute case (see Clause+++clause-8+++8.5), this + becomes a series of values (an array of JSON objects) and the operation + shall be run on each element of the array. + +2. The _`type`_ sub-attribute of the JSON object (which is used to define the + _Attribute's_ data type) is removed. + +3. Where the JSON object contains only one single sub-attribute + ["value"]{.HTML-Code}, + - if that sub-attribute's _`value`_ is a JSON primitive, the JSON object's + sub-attribute _`value`_, replaces the JSON object as a whole. + + - if that sub-attribute's _`value`_ parses as a GeoJSON object, the JSON + object's sub-attribute _`value`_, replaces the JSON object as a whole. + + - if that sub-attribute's _`value`_ is a JSON Object, no further changes are + made. + +4. Where the JSON object has more than one sub-attribute, or the sub-attribute + indicates a data type other than a _Property_ (i.e. ["object"]{.HTML-Code}, + ["languageMap"]{.HTML-Code}, ["vocab"]{.HTML-Code}, + ["valueList"]{.HTML-Code}, ["objectList"]{.HTML-Code}, ["json"]{.HTML-Code}) + the following compaction is applied: + - Any sub-attributes of the JSON object, that match attribute names of the + defined _Attribute_ data type (Clause+++root.2.6.4) are left unchanged. + + - Any remaining sub-attributes of the JSON object, that do not match the + defined attribute names of the _Attribute's_ data type are considered as + _Attributes_ of the _Attribute_ - recursively go to step 1. + +**Concise-to-Normalized Expansion** + +The expansion algorithm for concise to normalized can be achieved in the +following steps. + +For Each _Attribute_: + +1. Every Attribute is formed as a key-value pair, the key (left-hand-side) + being the Attribute Name and the value (right hand side) being the Attribute + value. In the multi-attribute case (see Clause+++clause-8+++8.5), this + becomes a series of values (an array of JSON objects) and the operation + shall be run on each element of the array. + +2. If the Attribute value parses as a valid GeoJSON object, the Attribute is + expanded to a _GeoProperty_ : + - The _GeoProperty_ _`type`_ is assigned ["type=GeoProperty"]{.HTML-Code} + - The _GeoProperty_ _`value`_ is assigned to the GeoJSON object. + + + +>>> [!tip] EXAMPLE 1: + +```json +"location": { + "type": "Point", + "coordinates": [54.112, 0.334] +} +``` + +>>> + + + +3. If the Attribute value is a JSON primitive the Attribute is expanded to a + _Property_ : + - The _Property_ _`type`_ is assigned ["type=Property"]{.HTML-Code} + - The _Property_ _`value`_ is assigned to the JSON primitive. + + + +>>> [!tip] EXAMPLE 2: + +```json +"name": "David Robert Jones" +``` + +>>> + + + + + +>>> [!note] NOTE: + +Note that the **concise format** of a _Property_ without sub-attributes matches +that of the **simplified format**. + +>>> + + + +4. If the Attribute value is a JSON object which contains the sub-attribute + ["value"]{.HTML-Code} and that _`value`_ parses as a valid GeoJSON object, + the Attribute is expanded to a _GeoProperty_: + - The _GeoProperty_ _`type`_ is assigned ["type=GeoProperty"]{.HTML-Code} + - The _GeoProperty_ _`value`_ is assigned to the _`value`_ sub-attribute of + the JSON object. + - Sub-attributes of the JSON object that match attribute names of the + _GeoProperty_ data type (Clause+++root.2.6.4.5) are assigned accordingly. + - Any remaining sub-attributes are considered as _Attributes_ of the + _GeoProperty_ - recursively go to step 1. + + + +>>> [!tip] EXAMPLE 4: + +```json +"location": { + "value": { + "type": "Point", + "coordinates": [54.112, 0.334] + }, + "observedAt": "2022-08-09T18:25:02Z" +} +``` + +>>> + + + +5. If the Attribute value is a JSON object which contains the sub-attribute + ["value"]{.HTML-Code} and that _`value`_ does not parse as a valid GeoJSON + object, the Attribute is expanded to a _Property_ : + - The _Property_ _`type`_ is assigned ["type=Property"]{.HTML-Code} + - The _Property_ _`value`_ is assigned to the _`value`_ sub-attribute of the + JSON object. + - Sub-attributes of the JSON object that match attribute names of the + _Property_ data type (Clause+++root.2.6.4.3) are assigned accordingly. + - Any remaining sub-attributes are considered as _Attributes_ of the + _Property_ recursively go to step 1. + + + +>>> [!tip] EXAMPLE 5: + +```json +"rainfall": { + "value": 0, + "unitCode": "MMT", + "observedAt": "2022-08-09T18:25:02Z" +} +``` + +>>> + +>>> [!tip] EXAMPLE 6: + +```json +"address": { + "value": { + "city": "Berlin", + "street": "Ulrich Strasse" + } +} +``` + +>>> + + + +6. If ["object"]{.HTML-Code} is present, the Attribute is expanded to a + _Relationship_ : + - The _Relationship_ _`type`_ is assigned ["type=Relationship"]{.HTML-Code} + - The _Relationship_ _`object`_ is assigned to the _`object`_ sub-attribute + of the JSON object. + - Sub-attributes of the JSON object that match attribute names of the + _Relationship_ data type (Clause+++root.2.6.4.4) are assigned accordingly. + - Any remaining other sub-attributes are considered as _Attributes_ of the + _Relationship_ - recursively go to step 1. + + + +>>> [!tip] EXAMPLE 7: + +```json +"locatedAt": { + "object": "urn:ngsi-ld:Place:0001", + "observedAt": "2022-08-09T18:25:02Z" +} +``` + +>>> + + + +7. If ["languageMap"]{.HTML-Code} is present, the Attribute is expanded to a + _LanguageProperty_ : + - The _LanguageProperty_ _`type`_ is assigned + ["type=LanguageProperty"]{.HTML-Code} + - The _LanguageProperty_ _`languageMap`_ is assigned to the _`languageMap`_ + sub-attribute of the JSON object. + - Sub-attributes of the JSON object that match attribute names of the + _LanguageProperty_ data type (Clause+++root.2.6.4.6) are assigned + accordingly. + - Any remaining other sub-attributes are considered as _Attributes_ of the + _LanguageProperty_ - recursively go to step 1. + + + +>>> [!tip] EXAMPLE 8: + +```json +"says": { + "languageMap": { + "en": "yes", + "fr": "oui" + }, + "observedAt": "2022-08-09T18:25:02Z" +} +``` + +>>> + + + +8. If ["vocab"]{.HTML-Code} is present, the Attribute is expanded to a + _VocabProperty_ : + - The _VocabProperty_ _`type`_ is assigned + ["type=VocabProperty"]{.HTML-Code} + - The _VocabProperty_ _`vocab`_ is assigned to the _`vocab`_ sub-attribute + of the JSON object. + - Further sub-attributes of the JSON object that match attribute names of + the _VocabProperty_ data type (Clause+++root.2.6.4.7) are assigned + accordingly. + - Any remaining other sub-attributes are considered as _Attributes_ of the + _VocabProperty_ - recursively go to step 1. + + + +>>> [!tip] EXAMPLE 9: + +```json +"status": { + "vocab": "Active", + "observedAt": "2022-08-09T18:25:02Z" +} +``` + +>>> + + + +9. If ["valueList"]{.HTML-Code} is present, the Attribute is expanded to a + _ListProperty_ : + - The _ListProperty_ _`type`_ is assigned ["type=ListProperty"]{.HTML-Code} + - The _ListProperty_ _`valueList`_ is assigned to the _`valueList`_ + sub-attribute of the JSON object. + - Further sub-attributes of the JSON object that match attribute names of the + _ListProperty_ data type (Clause+++root.2.6.4.8) are assigned accordingly. + - Any remaining other sub-attributes are considered as _Attributes_ of the + _ListProperty_ - recursively go to step 1. + + + +>>> [!tip] EXAMPLE 10: + +```json +"hourlyTemperature": { + "valueList": [9, 14, 17, 16, 12, 10, 9, 8], + "unitCode": "CEL", +} +``` + +>>> + + + +10. If ["objectList"]{.HTML-Code} is present, the Attribute is expanded to a + _ListRelationship_ + - The _ListRelationship_ _`type`_ is assigned + ["type=ListRelationship"]{.HTML-Code} + - The _ListRelationship_ _`objectList`_ is assigned to the _`objectList`_ + sub-attribute of the JSON object. + - Further sub-attributes of the JSON object that match attribute names of + the _ListRelationship_ data type (Clause+++root.2.6.4.9) are assigned + accordingly. + - Any remaining other sub-attributes are considered as _Attributes_ of the + _ListRelationship_ - recursively go to step 1. + + + +>>> [!tip] EXAMPLE 11: + +```json +"devices": { + "objectList": [ + "urn:ngsi-ld:Device:14142", + "urn:ngsi-ld:Device:13562", + "urn:ngsi-ld:Device:37309" + ], + "objectType": "urn:ngsi-ld:WeatherStation" +} +``` + +>>> + + + +12. If ["json"]{.HTML-Code} is present, the Attribute is expanded to a + _JsonProperty_: + - The _JsonProperty_ _`type`_ is assigned ["type=JsonProperty"]{.HTML-Code} + - The _JsonProperty_ _`json`_ is assigned to the _`json`_ sub-attribute of + the JSON object. + - Further sub-attributes of the JSON object that match attribute names of + the _JsonProperty_ data type (Clause+++root.2.6.4.10) are assigned + accordingly. + - Any remaining other sub-attributes are considered as _Attributes_ of the + _JsonProperty_ - recursively go to step 1. + + + +>>> [!tip] EXAMPLE 11: + +```json +"parkingTickets": { + "json": { + "id": "85a6cc52-0589-45f9", + "value": "Overstay 60 minutes" + }, + "providedBy": { + "object": "urn:ngsi-ld:traffic-warden:001" + } +} +``` + +>>> + + + +8. If none of the above apply, the Attribute is an invalid payload. + +#### 5.3.2.4 Entities Simplified + +The NGSI-LD specification defines an abbreviated, lossy representation of +Entities, which allows consuming only entity data (the target object of each +Relationship or the value of each Property) corresponding to the Attributes +whose subject is the Entity itself. The representation of Entities in the +**simplified format** shall be supported by implementations and can be selected +by [Context Consumers]{.HTML-Keyboard} through specific request parameters. An +example of this representation can be found in Annex C, Clause+++annex-c+++C.2.2 + +The representation of an Entity in the **simplified format** shall be a JSON-LD +object containing the following members: + +**Mandatory** + +- ["id"]{.HTML-Code} whose value shall be a URI that identifies the Entity. +- ["type"]{.HTML-Code} whose value shall be equal to the Entity Type name or an + unordered JSON array with multiple Entity Type names in case of an Entity that + has multiple Entity Types. + +**Optional** + +- ["@context",]{.HTML-Code} a JSON-LD _`@context`_ as described in + Clause+++root.3.2.1. +- For each _Attribute_, a key-value pair, the key (left-hand-side) being the + Attribute Name and the value (right hand side) being the Attribute value. the + format of the value is defined below, but shall vary for multi-attributes and + during [Linked Entity]{.HTML-Keyboard} **retrieval**. + +**Attribute Representation** + +For Each Attribute : + +- For each _Property_ a member whose key is the Property name (a term) and whose + value is the Property Value. + + + +>>> [!tip] EXAMPLE 1: + +```json +"name": "David Robert Jones" +``` + +>>> + + + +- For each _GeoProperty_, a member whose key is the Property name (a term) and + whose value is the Property Value. + + + +>>> [!tip] EXAMPLE 2: + +```json +"location": { + "type": "Point", + "coordinates": [13.3986, 52.5547] +} +``` + +>>> + + + +- For each _LanguageProperty_, a member whose key is the Property name (a term) + and whose value is a JSON Object containing a single Attribute with a key + called ["languageMap"]{.HTML-Code} where the value shall correspond to a + _LanguageProperty_ _`languageMap`_. + + + +>>> [!tip] EXAMPLE 3: + +```json +"says": { + "languageMap": { + "en": "yes", + "fr": "oui" + } +} +``` + +>>> + + + +- For each _JsonProperty_, a member whose key is the Property name (a term) and + whose value is a JSON Object containing a single Attribute with a key called + ["json"]{.HTML-Code} where the value shall correspond to the raw JSON data + that cannot be held in JSON-LD format. Within the example below, the + [id]{.HTML-Code} attribute is never expanded to [\@id]{.HTML-Code} and + therefore does not have to be defined as a URI, and the [value]{.HTML-Code} + attribute is never expanded to [ngsi-ld:hasValue]{.HTML-Code}. + + + +>>> [!tip] EXAMPLE 4: + +```json +"parkingTickets": { + "json": { + "id": "85a6cc52-0589-45f9", + "value": "Overstay 60 minutes" + } +} +``` + +>>> + + + +- For each _VocabProperty_, a member whose key is the Property name (a term) and + whose value is a JSON Object containing a single Attribute with a key called + ["vocab"]{.HTML-Code} where the value shall correspond to a _VocabProperty_ + _vocab_. + + + +>>> [!tip] EXAMPLE 5: + +```json +"gender": {"vocab": "Male"} +``` + +>>> + + + +- For each _Relationship_ a term whose key is the Relationship name (a term) and + whose value is the Relationship's Object (represented as a URI or array of + URIs). + + + +>>> [!tip] EXAMPLE 6: + +```json +"providedBy": "urn:ngsi-ld:Device:31415" +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 7: + +```json +"devices": [ + "urn:ngsi-ld:Device:14142", + "urn:ngsi-ld:Device:13562", + "urn:ngsi-ld:Device:37309" +] +``` + +>> + + + +- For each _ListProperty_ a member whose key is the Property name (a term) and + whose value is an ordered array holding the Property Values. + + + +>>> [!tip] EXAMPLE 8: + +```json +"periods": ["First", "Second", "Third", "Fourth"] +``` + +>>> + + + +- For each _ListRelationship_ a term whose key is the Relationship name (a term) + and whose value is an ordered array holding the _ListRelationship_'s Objects + (represented as URIs). + + + +>>> [!tip] EXAMPLE 9: + +```json +"route": [ + "urn:ngsi-ld:BusStop:0101", + "urn:ngsi-ld:BusStop:0102", + "urn:ngsi-ld:BusStop:9912" +] +``` + +>>> + + + +**Multi-Attribute Representation** + +In the multi-attribute case (see Clause+++clause-8+++8.5), the simplified format +of Attributes changes. + +For Each Attribute : + +- Each _Attribute_ consists of a key-value pair, the key being the Attribute + name and the value being a JSON Object, which contains a single Attribute with + a key called ["dataset"]{.HTML-Code}, and its value in turn is a JSON Object + holding a series of key-value pairs, one for each _`datasetId`_, where the + value corresponds to the simplified format of the Attribute value described + above. The default _`datasetId`_ (where present) is represented by the JSON-LD + keyword ["@none"]{.HTML-Code}. + + + +>>> [!tip] EXAMPLE 10: + +```json +"name": { + "dataset": { + "@none": "David Robert Jones", + "urn:ngsi-ld:datasetId:001": "David Bowie", + "urn:ngsi-ld:datasetId:002": "Ziggy Stardust" + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 11: + +```json +"parkingTickets": { + "dataset": { + "@none": { + "json": { + "id": "85a6cc52-0589-45f9", + "value": "Overstay 60 minutes" + } + }, + "urn:ngsi-ld:datasetId:001": { + "json": { + "id": "6663664-1234-4ee1", + "value": "Overstay 90 minutes" + } + }, + "urn:ngsi-ld:datasetId:002": { + "json": { + "id": "345560-8996-53f9", + "value": "Overstay 120 minutes" + } + } + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 12: + +```json +"says": { + "dataset": { + "@none": { + "languageMap": { + "en": "yes", + "fr": "oui" + } + }, + "urn:ngsi-ld:datasetId:001": { + "languageMap": { + "en": "certainly", + "fr": "certainement" + } + }, + "urn:ngsi-ld:datasetId:002": { + "languageMap": { + "en": "of course", + "fr": "bien sûr" + } + } + } +} +``` + +>>> + + + +**Representations of Linked Entities** + +In the [Linked Entity]{.HTML-Keyboard} **retrieval** case, the simplified format +of Relationships and Relationship subclasses changes. + +For Each Relationship (or subclass) : + +- In the inline [Linked Entity]{.HTML-Keyboard} **retrieval** case (see + Clause+++clause-7+++7.7.3), Any _Relationship_ which targets an Entity stored + locally or includes an _`objectType`_ Attribute is returned as a JSON object + holding key-value pairs corresponding to the data from the Relationship's + _`object`_ URI in simplified format. + + + +>>> [!tip] EXAMPLE 13: + +```json +"providedBy": { + "id": "urn:ngsi-ld:Device:31415", + "type": "Device", + "brandName": "Anemometer", + "manufacturerName": "Cyberdyne Systems", + "windSpeed": 60 +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 14: + +```json +"devices": [ + { + "id": "urn:ngsi-ld:Device:14142", + "type": "Device", + "brandName": "Anemometer", + "manufacturerName": "Cyberdyne Systems", + "windSpeed": 60 + }, + { + "id": "urn:ngsi-ld:Device:13562", + "type": "Device", + "brandName": "Hygromometer", + "manufacturerName": "Acme Corporation", + "humidity": 64 + }, + { + "id": "urn:ngsi-ld:Device:37309", + "type": "Device", + "brandName": "Barometer", + "manufacturerName": "Trask Industries", + "pressure": 760 + } +] +``` + +>>> + + + +- In the flattened [Linked Entity]{.HTML-Keyboard} **retrieval** case (see + Clause+++clause-7+++7.7), the simplified representation of a _Relationship_ + changes to return multiple Entities. Any _Relationships_ which target Entities + stored locally or include an _`objectType`_ Attribute are returned as part of + the array as an additional JSON object holding key-value pairs corresponding + to the data from the _Relationship's_ _`object`_ URI in simplified format. + + + +>>> [!tip] EXAMPLE 15: + +```json +[ + // ENTITY WITH A RELATIONSHIP ATTRIBUTE + { + … etc + "providedBy": "urn:ngsi-ld:Device:31415" + }, + // ADDITIONAL LINKED ENTITY + { + "id": "urn:ngsi-ld:Device:31415", + "type": "Device", + "brandName": "Anemometer", + "manufacturerName": "Cyberdyne Systems", + "windSpeed": 60 + } +] +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 16: + +```json +[ + // ENTITY WITH A RELATIONSHIP ATTRIBUTE + { + … etc + "providedBy": [ + "urn:ngsi-ld:Device:14142", + "urn:ngsi-ld:Device:13562", + "urn:ngsi-ld:Device:37309" + ] + }, + // ADDITIONAL LINKED ENTITIES + { + "id": "urn:ngsi-ld:Device:14142", + "type": "Device", + "brandName": "Anemometer", + "manufacturerName": "Cyberdyne Systems", + "windSpeed": 60 + }, + { + "id": "urn:ngsi-ld:Device:13562", + "type": "Device", + "brandName": "Hygromometer", + "manufacturerName": "Acme Corporation", + "humidity": 64 + }, + { + "id": "urn:ngsi-ld:Device:37309", + "type": "Device", + "brandName": "Barometer", + "manufacturerName": "Trask Industries", + "pressure": 760 + } +] +``` + +>>> + + + + + +- In the inline [Linked Entity]{.HTML-Keyboard} **retrieval** case (see + Clause+++clause-7+++7.7.3), any _ListRelationship_ which targets Entities + stored locally or includes an _`objectType`_ Attribute is returned as an + ordered array of JSON objects holding key-value pairs corresponding to the + data from the _ListRelationship_'s target _`objectList`_ URIs in simplified + format. + + + +>>> [!tip] EXAMPLE 17: + +```json +"route": [ + { + "id": "urn:ngsi-ld:BusStop:0101", + "type": "BusStop", + "stopName": "High Street", + "location": { + "type": "Point", "coordinates": [54.112, 13.334] + } + }, + { + "id": "urn:ngsi-ld:BusStop:0102", + "type": "BusStop", + "stopName": "Station Road", + "location":{ + "type": "Point", "coordinates": [54.101, 13.302] + } + }, + { + "id": "urn:ngsi-ld:BusStop:9912", + "type": "BusStop", + "stopName": "Mornington Cresent", + "location":{ + "type": "Point", "coordinates": [54.142, 13.332] + } + } +] +``` + +>>> + + + +- In the flattened [Linked Entity]{.HTML-Keyboard} **retrieval** case (see + Clause+++clause-7+++7.7), the simplified format of a _ListRelationship_ + changes to return multiple Entities. Any _ListRelationships_ which target + Entities stored locally or include an _`objectType`_ Attribute are returned as + additional JSON objects holding key-value pairs corresponding to the data from + the _ListRelationship_'s target _`objectList`_ URIs in simplified format. + + + +>>> [!tip] EXAMPLE 18: + +```json +[ + // ENTITY WITH A LIST RELATIONSHIP ATTRIBUTE + { + … etc + "route": [ + "urn:ngsi-ld:BusStop:0101", + "urn:ngsi-ld:BusStop:0102", + "urn:ngsi-ld:BusStop:9912" + ] + }, + // ADDITIONAL LINKED ENTITIES + { + "id": "urn:ngsi-ld: BusStop:0101", + "type": "BusStop", + "stopName": "High Street", + "location": { + "type": "Point", + "coordinates": [54.112, 13.334] + } + }, + { + "id": "urn:ngsi-ld: BusStop:0102", + "type": "BusStop", + "stopName": "Station Road", + "location": { + "type": "Point", + "coordinates": [54.101, 13.302] + } + }, + { + "id": "urn:ngsi-ld:BusStop:9912", + "type": "BusStop", + "stopName": "Mornington Cresent", + "location": { + "type": "Point", + "coordinates": [54.142, 13.332] + } + } +] +``` + +>>> + + + +#### 5.3.2.5 Temporal Normalized + +The temporal representation of an Entity is the way to represent the [Temporal +Evolution of an Entity]{.HTML-Keyboard}: the Entity shall be as mandated by +Clause+++root.3.2.2, but for each Property and Relationship their temporal +representation shall be provided and the Scope (if present) shall be represented +as a temporal representation of a Property that can only have the non-reified +Temporal Properties _`createdAt`_, _`modifiedAt`_, _`deletedAt`_ and +_`observedAt`_ as sub-Properties. This is required to represent the Scope of a +[Temporal Evolution of an Entity]{.HTML-Keyboard}. In case the Temporal +Evolution of the Scope is updated as the result of a change from the [Core +API]{.HTML-Keyboard}, the _observedAt_ sub-Property should be set as a copy of +the _`modifiedAt`_ sub-Property. + +**Temporal Representation of Entity Attributes** + +The temporal evolution of an _Attribute_ (for instance, its historical evolution +or future predictions) is composed of the sequence of instances of the referred +during a period of time within its lifetime. + +The temporal representation of an _Attribute_ shall be provided as an Array of +JSON-LD objects (or a single JSON-LD object in case only one is present), each +one representing an instance of the Attribute (as mandated by +Clause+++root.2.6.4) at a particular point in time, which is recorded as a +Temporal Property of the instance (typically _`observedAt`_). See example in +Annex A, Clause+++annex-a+++A.6. In case the _Attribute_ is deleted, an instance +of the _Property_ is recorded with its _value_ set to the URI +["urn:ngsi-ld:null"]{.HTML-Code} and the _`deletedAt`_ Temporal Property set. + +Systems should maintain an _instanceId_ for each such _Property_ instance. +Without such an _`instanceId`_, it is not possible to selectively modify or +delete temporal information via the NGSI-LD API. The consequences of this may be +severe in the case of modification or deletion requests for legal reasons, e.g. +GDPR [i.17]. When implementing the NGSI-LD API on storage systems that do NOT +allow modification or deletion, similar problems may be encountered. + +**Mandatory** + +For Each _Attribute_, one of the following members shall be present: + +- ["values"]{.HTML-Code} indicating the temporal evolution of a _Property_ - + further members shall follow the data type described in Clause+++root.2.6.4.3 +- ["objects"]{.HTML-Code} indicating the temporal evolution of a + _Relationship_ - further members shall follow the data type described in + Clause+++root.2.6.4.4 +- ["values"]{.HTML-Code} indicating the temporal evolution of a _GeoProperty_ - + further members shall follow the data type described in Clause+++root.2.6.4.5 +- ["languageMaps"]{.HTML-Code} indicating the temporal evolution of a + _LanguageProperty_ Attribute - further members shall follow the data type + described in Clause+++root.2.6.4.6 +- ["vocabs"]{.HTML-Code} indicating the temporal evolution of a + _VocabProperty_ - further members shall follow the data type described in + Clause+++root.2.6.4.7 +- ["valueLists"]{.HTML-Code} indicating the temporal evolution of a + _ListProperty_ - further members shall follow the data type described in + Clause+++root.2.6.4.8 +- ["objectLists"]{.HTML-Code} indicating the temporal evolution of a + _ListRelationship_ Attribute - further members shall follow the data type + described in Clause+++root.2.6.4.9 +- ["jsons"]{.HTML-Code} indicating the temporal evolution of a _JsonProperty_ - + further members +- shall follow the data type described in Clause+++root.2.6.4.10 + +On an _Attribute_, the following member is also mandatory, aligning with the +data type described above: + +- ["type"]{.HTML-Code}: a fixed value describing the Attribute data type, one of + the following values: + - ["Property"]{.HTML-Code}, ["Relationship"]{.HTML-Code}, + ["GeoProperty"]{.HTML-Code}, ["LanguageProperty"]{.HTML-Code}, + ["VocabProperty"]{.HTML-Code}, ["ListProperty"]{.HTML-Code}, + ["Relationship"]{.HTML-Code}, ["JsonProperty"]{.HTML-Code} + +#### 5.3.2.6 Temporal Simplified + +The NGSI-LD specification defines an alternative, abbreviated temporal +representation of [Temporal Evolution of Entities]{.HTML-Keyboard}, which allows +consuming temporal Entity data in a more straightforward manner. The simplified +temporal representation of Entities shall be supported by implementations and +can be selected by [Context Consumers]{.HTML-Keyboard} through specific request +parameters. An example can be found in Annex A, Clause+++annex-a+++A.5.6. + +The simplified temporal representation of an Entity shall be a JSON-LD object +containing the following members: + +**Mandatory** + +- ["id"]{.HTML-Code} whose value shall be a URI that identifies the Entity. +- ["type"]{.HTML-Code} whose value shall be equal to the Entity Type name or an + unordered JSON array with multiple Entity Type names in case of an Entity that + has multiple Entity Types. + +**Optional** + +- ["@context"]{.HTML-Code}, a JSON-LD _`context`_ as described in + Clause+++root.3.2.1. +- For each _Property_, a member whose key is the Property name (a term), the + member value shall be a JSON-LD object labelled with the type + ["Property"]{.HTML-Code}. Such JSON-LD object shall only contain a member + whose key shall be ["values"]{.HTML-Code}. The value of the referred + ["values"]{.HTML-Code} member shall be a JSON-LD Array that shall contain as + many array elements as _Property_ instances (i.e. data points of the concerned + _Property_) being represented. Each array element shall be another Array + containing exactly two array elements: the first element shall be a Property + value and the second element shall correspond to the associated Temporal + Property (for instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 1: + +```json +"name": { + "type": "Property", + "values": [ + [ + "Joe Bloggs", + "2022-08-09T18:25:02Z" + ], + [ + "Bill Smith", + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + +- For each _GeoProperty_, a member whose key is the Property name (a term), the + member value shall be a JSON-LD object labelled with the type + ["GeoProperty"]{.HTML-Code}. Such JSON-LD object shall only contain a member + whose key shall be ["values"]{.HTML-Code}. The value of the referred + ["values"]{.HTML-Code} member shall be a JSON-LD Array that shall contain as + many array elements as _GeoProperty_ instances (i.e. data points of the + concerned _GeoProperty_) being represented. Each array element shall be + another Array containing exactly two array elements: the first element shall + be a _GeoProperty_ _`value`_ and the second element shall correspond to the + associated Temporal Property (for instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 2: + +```json +"location": { + "type": "GeoProperty", + "values": [ + [ + {"type": "Point", "coordinates": [54.112, 0.334]}, + "2022-08-09T18:25:02Z" + ], + [ + {"type": "Point", "coordinates": [54.110, 0.338]}, + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + +- For each _LanguageProperty_, a member whose key is the Property name (a term), + the member value shall be a JSON-LD object labelled with the type + ["LanguageProperty"]{.HTML-Code}. Such JSON-LD object shall only contain a + member whose key shall be ["languageMaps"]{.HTML-Code}. The value of the + referred ["languageMaps"]{.HTML-Code} member shall be a JSON-LD Array that + shall contain as many array elements as _LanguageProperty_ instances (i.e. + data points of the concerned _LanguageProperty_) being represented. Each array + element shall be another Array containing exactly two array elements: the + first element shall be a JSON Object containing a single Attribute with a key + called ["languageMap"]{.HTML-Code} where the value shall correspond to a + _LanguageProperty_ _`languageMap`_ and the second element shall correspond to + the associated Temporal Property (for instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 3: + +```json +"says": { + "type": "LanguageProperty", + "languageMaps": [ + [ + {"languageMap": {"en": "yes", "fr": "oui"}}, + "2022-08-09T18:25:02Z" + ], + [ + {"languageMap": {"en": "no", "fr": "non"}}, + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + +- For each _ListProperty_, a member whose key is the Property name (a term), the + member value shall be a JSON-LD object labelled with the type + ["ListProperty"]{.HTML-Code}. Such JSON-LD object shall only contain a member + whose key shall be ["valueLists"]{.HTML-Code}. The value of the referred + ["valueLists"]{.HTML-Code} member shall be a JSON-LD Array that shall contain + as many array elements as _ListProperty_ instances (i.e. data points of the + concerned _ListProperty_) being represented. Each array element shall be + another array containing exactly two elements: the first element shall be an + ordered array of Property values, and the second element shall correspond to + the associated Temporal Property (for instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 4: + +```json +"period": { + "type": "ListProperty", + "valueLists": [ + [ + ["First", "Second", "Third", "Fourth"], + "2022-08-09T18:25:02Z" + ], + [ + ["1st", "2nd", "3rd", "4th"], + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + +- For each _JsonProperty_, a member whose key is the Property name (a term), the + member value shall be a JSON-LD object labelled with the type + ["JsonProperty"]{.HTML-Code}. Such JSON-LD object shall only contain a member + whose key shall be ["jsons"]{.HTML-Code}. The value of the referred + ["jsons"]{.HTML-Code} member shall be a JSON-LD Array that shall contain as + many array elements as _JsonProperty_ instances (i.e. data points of the + concerned _JsonProperty_) being represented. Each array element shall be + another Array containing exactly two array elements: the first element shall + be a JSON Object containing a single Attribute with a key called + ["json"]{.HTML-Code}, where the value shall correspond to raw JSON data that + cannot be held in JSON-LD format and the second element shall correspond to + the associated Temporal Property (for instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 5: + +```json +"parkingTickets": { + "type": "JsonProperty", + "jsons": [ + [ + { + "json": [ + { + "id": "85a6cc52-0589-45f9", + "value": "Overstay 60 minutes" + } + ], + }, + "2022-08-09T18:25:02Z" + ], + [ + { + "json": [ + { + "id": "85a6cc52-0589-45f9", + "value": "Overstay 60 minutes" + }, + { + "id": "x5c56s-0589-45f9", + "value": "Overstay 45 minutes" + } + ] + }, + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + +- For each _VocabProperty_, a member whose key is the Property name (a term), + the member value shall be a JSON-LD object labelled with the type + ["VocabProperty"]{.HTML-Code}. Such JSON-LD object shall only contain a member + whose key shall be ["vocabs"]{.HTML-Code}. The value of the referred + ["vocabs"]{.HTML-Code} member shall be a JSON-LD Array that shall contain as + many array elements as _VocabProperty_ instances (i.e. data points of the + concerned _VocabProperty_) being represented. Each array element shall be + another Array containing exactly two array elements: the first element shall + be a JSON Object containing a single Attribute with a key called + ["vocab"]{.HTML-Code}, where the value shall correspond to a + [VocabProperty]{.HTML-Keyboard} _`vocab`_ and the second element shall + correspond to the associated Temporal Property (for instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 6: + +```json +"gender": { + "type": "VocabProperty", + "vocabs": [ + [ + {"vocab": "Male"}, + "2022-08-09T18:25:02Z" + ], + [ + {"vocab": "Female"}, + "2022-08-10T18:25:02Z" + ] + ] +``` + +>>> + + + +- For each _Relationship_, a term whose key is the Relationship name (a term). + The member value shall be a JSON-LD object labelled with the type + ["Relationship"]{.HTML-Code}. Such JSON-LD object shall only contain a member + whose key shall be ["objects"]{.HTML-Code}. The value of the referred + ["objects"]{.HTML-Code} member shall be a JSON-LD Array that shall contain as + many array elements as _Relationship_ instances (i.e. data points of the + concerned _Relationship_) being represented. Each array element shall be + another array containing exactly two elements: the first element shall be a + _Relationship_ object (a URI or array of URIs) and the second element shall + correspond to the associated Temporal Property (for instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 7: + +```json +"locatedAt": { + "type": "Relationship", + "objects": [ + [ + "urn:ngsi-ld:Place:123455", + "2022-08-09T18:25:02Z" + ], + [ + "urn:ngsi-ld:Place:999999", + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 8: + +```json +"activeDevices": { + "type": "Relationship", + "objects": [ + [ + ["urn:ngsi-ld:Device:14142", "urn:ngsi-ld:Device:13562"], + "2022-08-09T18:25:02Z" + ], + [ + ["urn:ngsi-ld:Device:14142", "urn:ngsi-ld:Device:13562", "urn:ngsi-ld:Device:37309"], + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + +- For each _ListRelationship_, a term whose key is the Relationship name (a + term), the member value shall be a JSON-LD object labelled with the type + ["ListRelationship"]{.HTML-Code}. Such JSON-LD object shall only contain a + member whose key shall be ["objectLists"]{.HTML-Code}. The value of the + referred["objectLists"]{.HTML-Code} member shall be a JSON-LD Array that shall + contain as many array elements as _ListRelationship_ instances (i.e. data + points of the concerned _ListRelationship_) being represented. Each array + element shall be another array containing exactly two elements: the first + element shall be an ordered array of Relationship objects (URIs) and the + second element shall correspond to the associated Temporal Property (for + instance _`observedAt`_). + + + +>>> [!tip] EXAMPLE 9: + +```json +"membersPresent": { + "type": "ListRelationship", + "objectLists": [ + [ + ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], + "2022-08-09T18:25:02Z" + ], + [ + ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Eve", "urn:ngsi-ld:Person:Mallory"], + "2022-08-10T18:25:02Z" + ] + ] +} +``` + +>>> + + + +#### 5.3.2.7 Temporal Aggregated + +The NGSI-LD specification defines an alternative temporal representation of +Entities, called aggregated temporal representation, which allows consuming +temporal Entity data after applying an aggregation function on the values of the +Attribute instances. The aggregated temporal representation of Entities shall be +supported by implementations supporting the temporal representation of Entities +and can be selected by [Context Consumers]{.HTML-Keyboard} through specific +request parameters. An example can be found in Annex A, Clause+++annex-a+++A.14. + +The aggregation function is applied according to the following principles: + +- An aggregation method specifies the function used to aggregate the values + (e.g. sum, mean, etc.). A [Context Consumer]{.HTML-Keyboard} can ask for many + aggregation methods in one request. +- The duration of an aggregation period specifies the duration of each period to + be used when applying the aggregation function on the values of a Temporal + Entity. + +The aggregated temporal representation of an Entity shall include the following: + +- A JSON-LD object containing the following members: + - _`id`_, _`type`_ and _`@context`_ as described in Clause+++root.3.2.2. + - For each _Property_ a member whose key is the Property name (a term). The + member value shall be a JSON-LD object labelled with the type + ["Property"]{.HTML-Code}. Such JSON-LD object shall contain one member per + aggregation method requested by the [Context Consumer]{.HTML-Keyboard}. Each + member uses the aggregation method name as a key. The value of each member + shall be a JSON-LD Array that shall contain as many array elements as there + are periods in the time range of the query. Each array element shall be + another Array containing exactly three array elements in the following + order: + 1. the value obtained after applying the aggregation method over the + period; + 2. the start _DateTime_ + 3. the end _DateTime_ + + - For each _Relationship_ a term whose key is the Relationship name (a term). + The member value shall be a JSON-LD object labelled with the type + ["Relationship"]{.HTML-Code}. Such JSON-LD object shall contain one member + per aggregation method requested by the [Context Consumer]{.HTML-Keyboard}. + Each member uses the aggregation method name as a key. The value of each + member shall be a JSON-LD Array that shall contain as many array elements as + there are periods in the time range of the query. Each array element shall + be another array containing exactly three array elements in the following + order: + 1. the value obtained after applying the aggregation method over the + period; + 2. the start _DateTime_ + 3. the end _DateTime_ + +An example of this aggregated temporal representation can be found in Annex A, +Clause+++annex-a+++A.14 + +**Supported behaviours for aggregation functions** + +In order to support such aggregation functions, two parameters are defined: + +- _`aggrMethods`_, to express the aggregation methods to apply. +- _`aggrPeriodDuration`_ to express the duration of the period to consider in + each step of the aggregation. + +The duration is expressed using the ISO 8601 [n.5] Duration Representation and +in particular using the following format and conventions: + +- The duration shall be a string in the format + [P\[n\]Y\[n\]M\[n\]DT\[n\]H\[n\]M\[n\]S]{.HTML-Code} or [P\[n\]W]{.HTML-Code}, + where [\[n\]]{.HTML-Code} is replaced by the value for each of the date and + time elements that follow the [\[n\]]{.HTML-Code}, [P]{.HTML-Code} is the + duration designator and [T]{.HTML-Code} is the time designator. For example, + ["P3Y6M4DT12H30M5S"]{.HTML-Code} represents a duration of "three years, six + months, four days, twelve hours, thirty minutes, and five seconds". +- Date and time elements including their designator may be omitted if their + value is zero. +- Lower-order elements may be omitted for reduced precision. +- A duration of 0 second (e.g. expressed as ["PT0S"]{.HTML-Code} or + ["P0D"]{.HTML-Code}) is valid and is interpreted as a duration spanning the + whole time range specified by the temporal query. +- Alternative representations based on combined date and time representations + are not allowed. + +The values supported by the _`aggrMethods`_ parameter are the following: + +- [aggrMethods = "avg" / "distinctCount" / "max" / "min" / "stddev" / "sum" / + "sumsq" / "totalCount"]{.HTML-Sample} + +The semantics of the different aggregation methods defined above is as follows, +and shall be supported by compliant implementations: + + + +::: TH +Table: Semantics of aggregation methods for Properties on JSON native data types +::: + +::: TAC ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| Aggregation Method | JSON String | JSON Number | JSON Object | JSON Array | JSON Boolean \ | +| | | | | | (see note) | ++====================+======================================================================+==================================================================+====================+===========================================================================+==================================================================+ +| avg | N/A | Calculate the average of the values inside the period | N/A | Calculate the average number of the sizes of the arrays inside the period | Calculate the average of the values inside the period | ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| distinctCount | Calculate the count of distinct values inside the period | ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| max | Calculate the last value in lexicographical order inside the period | Calculate the maximum value inside the period | N/A | Calculate the maximum size of the arrays inside the period | Calculate the maximum value inside the period | ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| min | Calculate the first value in lexicographical order inside the period | Calculate the minimum value inside the period | N/A | Calculate the minimum size of the arrays inside the period | Calculate the minimum value inside the period | ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| stddev | N/A | Calculate the standard deviation of the values inside the period | N/A | N/A | Calculate the standard deviation of the values inside the period | ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| sum | N/A | Calculate the sum of the values inside the period | N/A | Calculate the sum of the sizes of the arrays inside the period | Calculate the sum of the values inside the period | ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| sumsq | N/A | Calculate the sum of the square of the values inside the period | N/A | N/A | Calculate the sum of the square of the values inside the period | ++--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ +| totalCount | Calculate the number of times the value has been updated inside the period | ++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| >>> [!note] NOTE: | +| | +| For the purpose of aggregation, _`true`_ is considered as a value of 1, _`false`_ is considered as a value of 0. | +| | +| >>> | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Semantics of aggregation methods for Properties on other supported data types +::: + +::: TAC ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| Aggregation Method | DateTime | Date | Time | URI | ++========================+===============================================+===============================================+=====================================================================================================================================================+======================+ +| avg | N/A | N/A | Calculate the average time inside the period (e.g. to apply on an event that occurs at non fixed times, like the time a car enters a given parking) | N/A | ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| distinctCount | Calculate the count of distinct values inside the period | ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| max | Calculate the maximum value inside the period | Calculate the maximum value inside the period | Calculate the maximum value inside the period | N/A | ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| min | Calculate the minimum value inside the period | Calculate the minimum value inside the period | Calculate the minimum value inside the period | N/A | ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| stddev | N/A | N/A | N/A | N/A | ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| sum | N/A | N/A | N/A | N/A | ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| sumsq | N/A | N/A | N/A | N/A | ++------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ +| totalCount | Calculate the number of times the value has been updated inside the period | ++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Semantics of aggregation methods for Relationships +::: + +::: TAL ++-----------------------------------+-----------------------------------------------------------------------------------+ +| Aggregation Method | Relationship | ++:=================================:+===================================================================================+ +| avg | {TAC} | +| | | +| | N/A | ++-----------------------------------+-----------------------------------------------------------------------------------+ +| distinctCount | {TAC} | +| | | +| | Calculate the count of distinct relationships targets inside the period | ++-----------------------------------+-----------------------------------------------------------------------------------+ +| max | {TAC} | +| | | +| | N/A | ++-----------------------------------+-----------------------------------------------------------------------------------+ +| min | {TAC} | +| | | +| | N/A | ++-----------------------------------+-----------------------------------------------------------------------------------+ +| stddev | {TAC} | +| | | +| | N/A | ++-----------------------------------+-----------------------------------------------------------------------------------+ +| sum | {TAC} | +| | | +| | N/A | ++-----------------------------------+-----------------------------------------------------------------------------------+ +| sumsq | {TAC} | +| | | +| | N/A | ++-----------------------------------+-----------------------------------------------------------------------------------+ +| totalCount | {TAC} | +| | | +| | Calculate the number of times the relationship has been updated inside the period | ++-----------------------------------+-----------------------------------------------------------------------------------+ +::: + + + +### 5.3.3 GeoJSON + +#### 5.3.3.1 Introduction + +The NGSI-LD specification defines an alternative representation of Entities, to +make NGSI-LD responses compatible with GIS (Geographic Information System) +applications which support the GeoJSON format [n.4] and/or GeoJSON-LD [i.13]. + +Every NGSI-LD Entity can be represented as a GeoJSON _Feature_ object, where a +_Feature_ object represents any spatially bounded thing as defined by its +geometry. + +#### 5.3.3.2 Top-level "geometry" field selection algorithm + +A parameter of the request (named _`geometryProperty`_) may be used to indicate +the name of the _GeoProperty_ to be selected. If this parameter is not present, +then the default name of ["location"]{.HTML-Code} shall be used. + +If the selected _GeoProperty_ has multiple instances as described in +Clause+++clause-8+++8.5, either a _`datasetId`_ shall be specified, in order to +define which instance of the value is to be selected, or a default attribute +instance exists, which is then selected, if no _`datasetId`_ was specified. + +If an entity lacks the _GeoProperty_ as specified or the value does not hold a +valid GeoJSON _geometry_ object then the _`geometry`_ shall be undefined and +returned with a value of _`null`_ - which is syntactically valid GeoJSON. + +#### 5.3.3.3 Entities Normalized + +##### 5.3.3.3.1 Representation of an individual Entity + +The GeoJSON representation of a spatially bounded Entity in the **normalized +format** is defined as a single GeoJSON _Feature_ object including the following +members: + +**Mandatory** + +- ["geometry"]{.HTML-Code}: The value of the selected _GeoProperty_ (a GeoJSON + geometry object) used to define the spatial location of the Entity. Note that + no sub-Attributes of the selected _GeoProperty_ are present in the + representation. +- ["id"]{.HTML-Code}: the Entity id. +- ["properties"]{.HTML-Code}: A JSON object containing the following members: + - ["type"]{.HTML-Code}: the Entity Type name of the Entity or an unordered + JSON array with the Entity Type names of the Entity. + - One member for each _Attribute_ (including the selected _GeoProperty_) as + per the rules stated in Clause+++root.3.2.2. In case of multiple _Attribute_ + instances with the same Attribute name as described in + Clause+++clause-8+++8.5, all instances are provided as an unordered JSON + array. + +- ["type"]{.HTML-Code}: the fixed value ["Feature"]{.HTML-Code}. + +**Optional** + +- A JSON-LD _`@context`_ as described in Clause+++root.3.2.1 if requested as + part of the payload body. + +This representation shall be fully compliant with _Feature_ as defined within +IETF RFC 7946 [n.4]. + +An example can be found in Annex C, Clause+++annex-c+++C.2.3. + +##### 5.3.3.3.2 Representation of multiple Entities + +The GeoJSON representation of a list of spatially bounded Entities in the +**normalized format** is defined as a single GeoJSON _FeatureCollection_ object +containing an array of GeoJSON _Feature_ objects as follows: + +**Mandatory** + +- ["type"]{.HTML-Code}: the fixed value ["FeatureCollection"]{.HTML-Code}. +- ["features"]{.HTML-Code}: a JSON array of GeoJSON _Feature_ objects as defined + in Clause+++root.3.3.3.1. Note that separate _`@context`_ elements for each + _Feature_ will not be present in the payload body. + +**Optional** + +- A JSON-LD _`@context`_ as described in Clause+++root.3.2.1 if requested as + part of the payload body. + +This representation shall be fully compliant with _FeatureCollection_ as defined +within IETF RFC 7946 [n.4]. + +An example can be found in Annex C, Clause+++annex-c+++C.2.3. + +#### 5.3.3.4 Entities Concise + +##### 5.3.3.4.1 Representation of an individual Entity + +The GeoJSON representation of a spatially bounded Entity in the **concise +format** is defined as a single GeoJSON _Feature_ object, it differs from the +normalized format defined in Clause+++root.3.3.3.1 only in one respect, in that +within the ["properties"]{.HTML-Code} attribute, each _Attribute_ (including the +selected _GeoProperty_) is generated in the **concise format** according to the +rules defined in Clause+++root.3.2.3. + +An example can be found in Annex C, Clause+++annex-c+++C.2.3. + +##### 5.3.3.4.2 Representation of multiple Entities + +The GeoJSON representation of a list of spatially bounded Entities in the +**concise format** is defined as a single GeoJSON _FeatureCollection_ object +containing an array of GeoJSON _Feature_ objects as follows: + +**Mandatory** + +- ["type"]{.HTML-Code}: the fixed value ["FeatureCollection"]{.HTML-Code}. +- ["features"]{.HTML-Code}: a JSON array of GeoJSON _Feature_ objects as defined + in Clause+++root.3.3.4.1. Note that separate _`@context`_ elements for each + _Feature_ will not be present in the payload body. + +**Optional** + +- A JSON-LD _`@context`_ as described in Clause+++root.3.2.1 if requested as + part of the payload body. + +This representation shall be fully compliant with _FeatureCollection_ as defined +within IETF RFC 7946 [n.4]. + +An example can be found in Annex C, Clause+++annex-c+++C.2.3. + +#### 5.3.3.5 Entities Simplified + +##### 5.3.3.5.1 Representation of an individual Entity + +The GeoJSON representation of a spatially bounded Entity in the **simplified +format** is defined as a single GeoJSON _Feature_ object, it differs from the +normalized format defined in Clause+++root.3.3.3.1 only in one respect, in that +within the ["properties"]{.HTML-Code} attribute, each _Attribute_ (including the +selected _GeoProperty_) is generated in the **simplified format** according to +the rules defined in Clause+++root.3.2.4. + +An example can be found in Annex C, Clause+++annex-c+++C.2.3. + +##### 5.3.3.5.2 Representation of multiple Entities + +The GeoJSON representation of a list of spatially bounded Entities in the +**simplified format** is defined as a single GeoJSON _FeatureCollection_ object +containing an array of GeoJSON _Feature_ objects as follows: + +**Mandatory** + +- ["type"]{.HTML-Code}: the fixed value ["FeatureCollection"]{.HTML-Code}. +- ["features"]{.HTML-Code}: a JSON array of GeoJSON _Feature_ objects as defined + in Clause+++root.3.3.5.1. Note that separate _`@context`_ elements for each + _Feature_ will not be present in the payload body. + +**Optional** + +- A JSON-LD _`@context`_ as described in Clause+++root.3.2.1 if requested as + part of the payload body. + +This representation shall be fully compliant with _FeatureCollection_ as defined +within IETF RFC 7946 [n.4]. + +An example can be found in Annex C, Clause+++annex-c+++C.2.3. + +## 5.4 NGSI-LD fragments + +When updating NGSI-LD elements (Entities, Attributes, [Context Source +Registrations]{.HTML-Keyboard} or Subscriptions) it is necessary to have a means +of describing a set of modifications to their content. + +An NGSI-LD Fragment is a JSON Merge Patch document [n.17] and [i.18] which +describes changes to be made to a target JSON-LD document using a syntax that +closely mimics the document being modified. + +An NGSI-LD Fragment is a JSON-LD Object which shall include the following +members: + +- [id"]{.HTML-Code}: (optional for certain bindings where it can be determined + from the operation signature). It shall be equal to the _`id`_ of the target + (mutated) NGSI-LD element. Attribute Fragments do not contain explicit ids. +- ["type"]{.HTML-Code}: (optional for certain bindings where it can be + determined from the operation signature). It shall contain the Type name(s) of + the target NGSI-LD element. +- A member (following the same data representation and nesting structure) for + each new member **to be added** to the target NGSI-LD element. +- A member (following the same data representation and nesting structure) for + each new member **to be modified** in the target NGSI-LD element, which value + shall correspond to the new member value to be given. + + + +>>> [!tip] EXAMPLE 1: + +The following Subscription Fragment allows the modification of a Subscription by +changing its endpoint's URI: + +```json +{ + "id": "urn:ngsi-ld:Subscription:MySubscription", + "type": "Subscription", + "endpoint": { + "uri": "http://example.org/newNotificationEndPoint" + } +} +``` + +>>> + + + +When an NGSI-LD Fragment of an Entity by is received in the **concise format** +(see Clause+++root.3.2.3), it is first expanded into a normalized fragment +before being applied. + + + +>>> [!tip] EXAMPLE 2: + +The following Entity Fragment in the **concise format** allows the modification +of a Place Entity by changing elements of its _`address`_ Property _`value`_ +i.e a modification of a JSON Object which forms a Property. _`value`_. + +```json +{ + "id": "urn:ngsi-ld:Place:001", + "type": "Place", + "address": { + "value": { + "city": "Berlin", + "street": "Ulrich Strasse" + } + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +The following Entity Fragment in the **concise format** allows the modification +of a Place Entity by changing the _`value`_ of the _`verified`_ Property of the +_`address`_ Property. i.e a modification of a Property of a Property. + +```json +{ + "id": "urn:ngsi-ld:Place:001", + "type": "Place", + "address": { + "verfied" : true + } +} +``` + +>>> + + + +- A member (following the same data representation and nesting structure) with + value equal to an NGSI-LD Null shall cause for the member to be removed from + the target NGSI-LD element. + + + +>>> [!tip] EXAMPLE 4: + +The following NGSI-LD Fragment of an Entity in the **normalized format** allows the +modification the Entity by: + +- updating its _`locatedAt`_ _Relationship_ _`object`_ +- updating its _`batteryLevel`_ _Property_ _`value`_ +- updating the _`observedAt`_ _Property_ of the _`batteryLevel`_ _Property_ +- removing the _`providedBy`_ _Relationship_ of the _`batteryLevel`_ _Property_ +- removing the _`uncharged`_ _Property_ + +```json +{ + "id": "urn:ngsi-ld:TemperatureSensor:001", + "type": "TemperatureSensor", + "locatedAt": { + "type": "Relationship", + "object": "urn:ngsi-ld:Place:0001" + }, + "batteryLevel": { + "type": "Property", + "value": 7, + "observedAt": "2022-03-14T12:51:02.000Z", + "providedBy": "urn:ngsi-ld:null" + }, + "uncharged": { + "type": "Property", + "value": "urn:ngsi-ld:null" + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 4: + +The following NGSI-LD Fragment in the **concise format** allows the modification +of an Entity by: + +- updating its _`locatedAt`_ _Relationship_ _`object`_ +- updating its _`batteryLevel`_ _Property_ _`value`_ +- updating the _`observedAt`_ _Property_ of the _`batteryLevel`_ _Property_ +- removing the _`providedBy`_ _Relationship_ of the _`batteryLevel`_ _Property_ +- removing the _`uncharged`_ _Property_ + +```json +{ + "id": "urn:ngsi-ld:TemperatureSensor:001", + "type": "TemperatureSensor", + "locatedAt": { + "object": "urn:ngsi-ld:Place:0001" + }, + "batteryLevel": { + "value": 7, + "observedAt": "2022-03-14T12:51:02.000Z", + "providedBy": "urn:ngsi-ld:null" + }, + "uncharged": "urn:ngsi-ld:null" +} +``` + +>>> + + + +For a _LanguageProperty_ in the **normalized format** an NGSI-LD Null used +during partial update patch and merge patch (see Clause+++clause-8+++8.4.2 and +Clause+++clause-8+++8.4.3) shall be encoded as the JSON object [{"@none": +"urn:ngsi-ld:null"}]{.HTML-Code}. + + + +>>> [!tip] EXAMPLE 4: + +The following NGSI-LD Fragment in the **normalized format** removes the +_`exonym`_ _LanguageProperty_ from the Entity: + +```json +{ + "id": "urn:ngsi-ld:City:001", + "type": "City", + "exonym": { + "type": "LanguageProperty", + "languageMap": { + "@none": "urn:ngsi-ld:null" + } + } +} +``` + +>>> + + + +An NGSI-LD Null ["urn:ngsi-ld:null"]{.HTML-Code} can be used directly as the +value of a key-value pair for deletion of any Attribute in the **concise +format**. + + + +>>> [!tip] EXAMPLE 5: + +The following NGSI-LD Fragment in the **concise format** removes the _`exonym`_ +_LanguageProperty_ from the Entity: + +```json +{ + "id": "urn:ngsi-ld:City:001", + "type": "City", + "exonym": "urn:ngsi-ld:null" +} +``` + +>>> + + diff --git a/md/clause-6.md b/md/clause-6.md new file mode 100644 index 0000000000000000000000000000000000000000..dac9cf691bb4c5e92a30a5c9714ab69c46c83e3f --- /dev/null +++ b/md/clause-6.md @@ -0,0 +1,365 @@ +# 6 API structure + +As stated in clause 4.3.1, the NGSI-LD API is structured into a [Core +API]{.HTML-Keyboard} and an optional [Temporal API]{.HTML-Keyboard}. To support +the distributed and federated architectures described in clause 4.3.3, +distributed versions of the operations are needed. They are listed separately +under Distributed API and require the operations of the Registry API. The +[Registry API]{.HTML-Keyboard} consists of the operations to be implemented by +the [Context Registry]{.HTML-Keyboard}. Furthermore, the [JSONLDContext +API]{.HTML-Keyboard} provides functionality for storing, managing, and serving +JSON-LD _`@contexts`_. The APIs are structured according to their +functionalities, which is also reflected in how the operations are structured in +from ~clause 10 onwards. + +Table+++below introduces the API structure, the respective functionalities and +lists the operations for each functionality, pointing to the clauses in which +they are defined. The distributed versions of the operations are separately +shown in Table+++below under Distributed API, but there is a single clause for +each of the operations describing both the centralized and distributed +behaviour. In addition, the Distributed API has support operations only needed +in distributed and federated architectures. + + + +::: TH +Table: NGSI-LD API structure +::: + +::: TAL ++---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| API | Functionality | Operations | ++:==========================+:=======================================================================================================================================================================================================================+=================================================================================================+ +| {TAC} | _Context Information Provision_ - operations for providing or managing Entities and Attributes | Clause 10.2.2 Create Entity \ | +| | | Clause 10.2.3 Update Attributes \ | +| Core API | | Clause 10.2.4 Append Attributes \ | +| | | Clause 10.2.5 Partial Attribute Update \ | +| | | Clause 10.2.7 Delete Attribute \ | +| | | Clause 10.2.8 Delete Entity \ | +| | | Clause 10.3.2 Batch Entity Creation \ | +| | | Clause 10.3.3 Batch Entity Upsert \ | +| | | Clause 10.3.4 Batch Entity Update \ | +| | | Clause 10.3.6 Batch Entity Delete \ | +| | | Clause 10.2.9 Merge Entity \ | +| | | Clause 10.2.10 Replace Entity \ | +| | | Clause 10.2.11 Replace Attribute | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Context Information Consumption_ - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system | Clause 10.4.2 Retrieve Entity \ | +| | | Clause 10.4.3 Query Entities \ | +| | | Clause 10.6.3 Retrieve Available Entity Types \ | +| | | Clause 10.6.4 Retrieve Details of Available Entity Types \ | +| | | Clause 10.6.5 Retrieve Available Entity Type Information \ | +| | | Clause 10.6.6 Retrieve Available Attributes \ | +| | | Clause 10.6.7 Retrieve Details of Available Attributes \ | +| | | Clause 10.6.8 Retrieve Available Attribute Information \ | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Context Information Subscription_ - operations for subscribing to Entities, receiving notifications and managing subscriptions | Clause 10.5.2 Create Subscription \ | +| | | Clause 10.5.3 Update Subscription \ | +| | | Clause 10.5.4 Retrieve Subscription \ | +| | | Clause 10.5.5 Query Subscription \ | +| | | Clause 10.5.6 Delete Subscription \ | +| | | Clause 10.5.7 Notification | ++---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| {TAC} | _Temporal Context Information Provision_ - operations for providing or managing the Temporal Evolution of Entities and Attributes | Clause 11.2.2 Upsert Temporal Evolution of an Entity \ | +| | | Clause 11.2.3 Add Attributes to Temporal Evolution of an Entity \ | +| Temporal API | | Clause 11.2.4 Delete Attributes from Temporal Evolution of an Entity \ | +| | | Clause 11.2.5 Partial Update Attribute instance \ | +| | | Clause 11.2.6 Delete Attribute Instance \ | +| | | Clause 11.2.7 Delete Temporal Evolution of an Entity | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Temporal Context Information Consumption_ - operations for consuming the Temporal Evolution of Entities | Clause 11.3.2 Retrieve Temporal Evolution of an Entity \ | +| | | Clause 11.3.3 Query Temporal Evolution of Entities | ++---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| {TAC} | _Distributed Context Information Provision_ - operations for providing or managing Entities and Attributes | Clause 10.2.2 Create Entity (distributed) \ | +| | | Clause 10.2.3 Update Attributes (distributed) \ | +| Distributed API | | Clause 10.2.4 Append Attributes (distributed) \ | +| | | Clause 10.2.5 Partial Attribute Update (distributed) \ | +| | | Clause 10.2.7 Delete Attribute (distributed) \ | +| | | Clause 10.2.8 Delete Entity (distributed) \ | +| | | Clause 10.3.2 Batch Entity Creation (distributed) \ | +| | | Clause 10.3.3 Batch Entity Upsert (distributed) \ | +| | | Clause 10.3.4 Batch Entity Update (distributed) \ | +| | | Clause 10.3.6 Batch Entity Delete (distributed) \ | +| | | Clause 10.2.9 Merge Entity (distributed) \ | +| | | Clause 10.2.10 Replace Entity (distributed) \ | +| | | Clause 10.2.11 Replace Attribute (distributed) \ | +| | | Clause 10.3.5 Batch Entity Merge (distributed) | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Distributed Context Information Consumption_ - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system | Clause 10.4.2 Retrieve Entity (distributed) \ | +| | | Clause 10.4.3 Query Entities (distributed) \ | +| | | Clause 10.6.3 Retrieve Available Entity Types (distributed) \ | +| | | Clause 10.6.4 Retrieve Details of Available Entity Types (distributed) \ | +| | | Clause 10.6.5 Retrieve Available Entity Type Information (distributed) \ | +| | | Clause 10.6.6 Retrieve Available Attributes (distributed) \ | +| | | Clause 10.6.7 Retrieve Details of Available Attributes (distributed) \ | +| | | Clause 10.6.8 Retrieve Available Attribute Information (distributed) | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Distributed Context Information Subscription_ - operations for subscribing to Entities, receiving notifications and managing subscriptions | Clause 10.5.2 Create Subscription (distributed) \ | +| | | Clause 10.5.3 Update Subscription (distributed) \ | +| | | Clause 10.5.4 Retrieve Subscription (distributed) \ | +| | | Clause 10.5.5 Query Subscription (distributed) \ | +| | | Clause 10.5.6 Delete Subscription (distributed) \ | +| | | Clause 10.5.7 Notification (distributed) | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Distributed Temporal Context Information Provision_ - operations for providing or managing the Temporal Evolution of Entities and Attributes | Clause 11.2.2 Upsert Temporal Evolution of an Entity (distributed) \ | +| | | Clause 11.2.3 Add Attributes to Temporal Evolution of an Entity (distributed) \ | +| | | Clause 11.2.4 Delete Attributes from Temporal Evolution of an Entity (distributed) \ | +| | | Clause 11.2.5 Partial Update Attribute instance (distributed) \ | +| | | Clause 11.2.6 Delete Attribute Instance (distributed) \ | +| | | Clause 11.2.7 Delete Temporal Evolution of an Entity (distributed) | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Distributed Temporal Context Information Consumption_ - operations for consuming the Temporal Evolution of Entities | Clause 11.3.2 Retrieve Temporal Evolution of an Entity (distributed) \ | +| | | Clause 11.3.3 Query Temporal Evolution of Entities (distributed) | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Support operations for distributed operations_ - operations enable more consistent pagination in the distributed case (EntityMap) and the prevention of request loops (Context Source Identity Information). | Clause 14.2 Retrieve EntityMap \ | +| | | Clause 14.3 Update EntityMap \ | +| | | Clause 14.4 Delete EntityMap \ | +| | | Clause 14.5 Create EntityMap for Query Entities \ | +| | | Clause 14.6 Create EntityMap for Query Temporal Evolution of Entities \ | +| | | Clause 15.2 Retrieve Context Source Identity Information | ++---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| {TAC} | _Context Source Registration_ - operations for registering Context Sources and managing Context Source Registrations (CSRs) | Clause 12.2.2 Register Context Source \ | +| | | Clause 12.2.3 Update CSR \ | +| Registry API | | Clause 12.2.4 Delete CSR | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Context Source Discovery_ - operations for retrieving and discovering CSRs | Clause 10.4.2 Retrieve CSR \ | +| | | Clause 10.4.3 Query CSRs | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| | _Context Source Registration Subscription_ - operations for subscribing to CSRs, receiving notifications and managing CSRs | Clause 12.4.2 Create CSR Subscription \ | +| | | Clause 12.4.3 Update CSR Subscription \ | +| | | Clause 12.4.4 Retrieve CSR Subscription \ | +| | | Clause 12.4.5 Query CSR Subscription \ | +| | | Clause 12.4.6 Delete CSR Subscription \ | +| | | Clause 12.4.7 CSR Notification | ++---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| {TAC} | _Snapshot Management_ - operations for creating and managing Snapshots. | Clause 16.2 Create Snapshot \ | +| | | Clause 16.3 Clone Snapshot \ | +| Snapshot API | | Clause 16.4 Retrieve Snapshot Status \ | +| | | Clause 16.5 Update Snapshot Status \ | +| | | Clause 16.6 Delete Snapshot \ | +| | | Clause 16.8 Snapshot Status Notification | ++---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| {TAC} | _JSON-LD \@Context Management_ - operations for storing, managing and serving JSON-LD _`@contexts`_ | Clause 13.2 Add \@context \ | +| | | Clause 13.3 List \@contexts \ | +| JSONLDContext API | | Clause 13.4 Serve \@context \ | +| | | Clause 13.5 Delete and Reload \@context | ++---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +::: + + + +All [Context Brokers]{.HTML-Keyboard} shall implement the [Core +API]{.HTML-Keyboard}. [Context Brokers]{.HTML-Keyboard} supporting distributed +and federated deployments shall also implement the Distributed API. [Temporal +API]{.HTML-Keyboard} and [Registry API]{.HTML-Keyboard} can be implemented by a +Broker or by a separate temporal component and [Context +Registry]{.HTML-Keyboard} respectively. Table+++below shows the possible +implementation configurations. A temporal component implementing the [Temporal +API]{.HTML-Keyboard} can also be used completely independently of a [Context +Broker]{.HTML-Keyboard}. The [Snapshot API]{.HTML-Keyboard} and the +[JSONLDContext API]{.HTML-Keyboard} are optional. The managing and serving of +_`@contexts`_ can also be handled by an independent, stand-alone component. + + + +::: TH +Table: Main implementation configurations +::: + +::: TAL ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Description | Temporal API | RegistryAPI | ++==============================================================================================================================================================================================================================================================+=============================================+===============+ +| Central Broker without temporal support | none | none | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Central Broker with integrated temporal component | local | none | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Central Broker with separate temporal component | separate | none | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Context Broker supporting distributed and federated deployments without temporal support and with integrated Context Registry | none | local | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Context Broker supporting distributed and federated deployments with integrated temporal component and integrated Context Registry | local | local | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Context Broker supporting distributed and federated deployments with separate temporal component and integrated Context Registry | separate | local | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Context Broker supporting distributed and federated deployments without temporal support and separate Context Registry | none | separate | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Context Broker supporting distributed and federated deployments with integrated temporal component and separate Context Registry | local | separate | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +| Context Broker supporting distributed and federated deployments with separate temporal component and separate Context Registry | separate | separate | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+---------------+ +::: + + + +Table+++below shows which operations are implemented and used by the other +architectural roles as introduced in clause 4.3.2 and clause 4.3.3. In addition, +there are separate roles for the Temporal API, i.e. Temporal [Context +Producer]{.HTML-Keyboard}, Temporal [Context Source]{.HTML-Keyboard} and +Temporal [Context Consumer]{.HTML-Keyboard}. For completeness, the roles of +Context Repository and Temporal Context Repository have been introduced, +implementing the Context Information Provision and Temporal Context Information +Provision functionalities, respectively. In practice, components implementing +the latter roles will also implement functionalities for consuming or processing +the stored information. Actual components can have multiple roles at the same +time, e.g. a [Context Broker]{.HTML-Keyboard} can implement all roles at the +same time. [Context Consumers]{.HTML-Keyboard} typically only interact with +[Context Brokers]{.HTML-Keyboard}, but in alternative setups, as shown in +Figure+++image14.png, they can also directly interact with the [Context +Registry]{.HTML-Keyboard} and then directly contact [Context +Sources]{.HTML-Keyboard}. + + + +::: TH +Table: Operations implemented by the various NGSI-LD Roles +::: + +::: TAL ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| NGSI-LD Role | Implements | Uses | ++============================================+============================================================================================================================================================================================+===========================================================================================================+ +| Context Consumer | Clause 10.5.7 Notification - **if supporting asynchronous interactions** | Clause 10.4.2 Retrieve Entity \ | +| | | Clause 10.4.3 Query Entities \ | +| | **In case of direct interactions with Context Registry:** | Clause 10.6.3 Retrieve Available Entity Types \ | +| | | Clause 10.6.4 Retrieve Details of Available Entity Types \ | +| | Clause 12.4.7 CSR Notification - **if supporting asynchronous interactions** | Clause 10.6.5 Retrieve Available Entity Type Information \ | +| | | Clause 10.6.6 Retrieve Available Attributes \ | +| | | Clause 10.6.7 Retrieve Details of Available Attributes \ | +| | | Clause 10.6.8 Retrieve Available Attribute Information \ | +| | | Clause 10.5.2 Create Subscription \ | +| | | Clause 10.5.3 Update Subscription \ | +| | | Clause 10.5.4 Retrieve Subscription \ | +| | | Clause 10.5.5 Query Subscription \ | +| | | Clause 10.5.6 Delete Subscription \ | +| | | Clause 14.2 Retrieve EntityMap \ | +| | | Clause 14.3 Update EntityMap \ | +| | | Clause 14.4 Delete EntityMap \ | +| | | Clause 14.5 Create EntityMap for Query Entities \ | +| | | Clause 14.6 Create EntityMap for Query Temporal Evolution of Entities \ | +| | | Clause 15.2 Retrieve Context Source Identity Information \ | +| | | Clause 16.2 Create Snapshot \ | +| | | Clause 16.3 Clone Snapshot \ | +| | | Clause 16.4 Retrieve Snapshot Status \ | +| | | Clause 16.5 Update Snapshot Status \ | +| | | Clause 16.6 Delete Snapshot \ | +| | | Clause 16.8 Snapshot Status Notification \ | +| | | Clause 11.3.3 Query Temporal Evolution of Entities | +| | | | +| | | **In case of direct interactions with Context Registry:** | +| | | | +| | | Clause 10.4.2 Retrieve CSR \ | +| | | Clause 10.4.3 Query CSRs | +| | | | +| | | **if supporting asynchronous interactions:** | +| | | | +| | | Clause 12.4.2 Create CSR Subscription \ | +| | | Clause 12.4.3 Update CSR Subscription \ | +| | | Clause 12.4.4 Retrieve CSR Subscription \ | +| | | Clause 12.4.5 Query CSR Subscription \ | +| | | Clause 12.4.6 Delete CSR Subscription | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Context Producer | none | Clause 10.2.2 Create Entity \ | +| | | Clause 10.2.3 Update Attributes \ | +| | | Clause 10.2.4 Append Attributes \ | +| | | Clause 10.2.5 Partial Attribute Update \ | +| | | Clause 10.2.7 Delete Attribute \ | +| | | Clause 10.2.8 Delete Entity \ | +| | | Clause 10.3.2 Batch Entity Creation \ | +| | | Clause 10.3.3 Batch Entity Upsert \ | +| | | Clause 10.3.4 Batch Entity Update \ | +| | | Clause 10.3.6 Batch Entity Delete \ | +| | | Clause 10.2.9 Merge Entity \ | +| | | Clause 10.2.10 Replace Entity \ | +| | | Clause 10.2.11 Replace Attribute \ | +| | | Clause 10.3.5 Batch Entity Merge | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Context Source | Clause 10.4.2 Retrieve Entity \ | Clause 10.5.7 Notification \ | +| | Clause 10.4.3 Query Entities \ | Clause 12.2.2 Register Context Source \ | +| | Clause 10.6.3 Retrieve Available Entity Types \ | Clause 12.2.3 Update CSR \ | +| | Clause 10.6.4 Retrieve Details of Available Entity Types \ | Clause 12.2.4 Delete CSR | +| | Clause 10.6.5 Retrieve Available Entity Type Information \ | | +| | Clause 10.6.6 Retrieve Available Attributes \ | | +| | Clause 10.6.7 Retrieve Details of Available Attributes \ | | +| | Clause 10.6.8 Retrieve Available Attribute Information \ | | +| | Clause 10.5.2 Create Subscription \ | | +| | Clause 10.5.3 Update Subscription \ | | +| | Clause 10.5.4 Retrieve Subscription \ | | +| | Clause 10.5.5 Query Subscription \ | | +| | Clause 10.5.6 Delete Subscription \ | | +| | Clause 14.2 Retrieve EntityMap \ | | +| | Clause 14.3 Update EntityMap \ | | +| | Clause 14.4 Delete EntityMap \ | | +| | Clause 14.5 Create EntityMap for Query Entities \ | | +| | Clause 14.6 Create EntityMap for Query Temporal Evolution of Entities \ | | +| | Clause 15.2 Retrieve Context Source Identity Information | | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Context Repository | Clause 10.2.2 Create Entity \ | none | +| | Clause 10.2.3 Update Attributes \ | | +| | Clause 10.2.4 Append Attributes \ | | +| | Clause 10.2.5 Partial Attribute Update \ | | +| | Clause 10.2.7 Delete Attribute \ | | +| | Clause 10.2.8 Delete Entity \ | | +| | Clause 10.3.2 Batch Entity Creation \ | | +| | Clause 10.3.3 Batch Entity Upsert \ | | +| | Clause 10.3.4 Batch Entity Update \ | | +| | Clause 10.3.6 Batch Entity Delete \ | | +| | Clause 10.2.9 Merge Entity \ | | +| | Clause 10.2.10 Replace Entity \ | | +| | Clause 10.2.11 Replace Attribute \ | | +| | Clause 10.3.5 Batch Entity Merge \ | | +| | Clause 16.2 Create Snapshot \ | | +| | Clause 16.3 Clone Snapshot \ | | +| | Clause 16.4 Retrieve Snapshot Status \ | | +| | Clause 16.5 Update Snapshot Status \ | | +| | Clause 16.6 Delete Snapshot \ | | +| | Clause 16.8 Snapshot Status Notification | | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Temporal Context Consumer | **In case of direct interactions with Context Registry:** | Clause 11.3.2 Retrieve Temporal Evolution of an Entity \ | +| | | Clause 11.3.3 Query Temporal Evolution of Entities | +| | Clause 12.4.7 CSR Notification - **if supporting asynchronous interactions** | | +| | | **In case of direct interactions with Context Registry:** | +| | | | +| | | Clause 10.4.2 Retrieve CSR \ | +| | | Clause 10.4.3 Query CSRs | +| | | | +| | | **if supporting asynchronous interactions**: | +| | | | +| | | Clause 12.4.2 Create CSR Subscription \ | +| | | Clause 12.4.3 Update CSR Subscription \ | +| | | Clause 12.4.4 Retrieve CSR Subscription \ | +| | | Clause 12.4.5 Query CSR Subscription \ | +| | | Clause 12.4.6 Delete CSR Subscription | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Temporal Context Producer | None | Clause 11.2.2 Upsert Temporal Evolution of an Entity \ | +| | | Clause 11.2.3 Add Attributes to Temporal Evolution of an Entity \ | +| | | Clause 11.2.4 Delete Attributes from Temporal Evolution of an Entity \ | +| | | Clause 11.2.5 Partial Update Attribute instance \ | +| | | Clause 11.2.6 Delete Attribute Instance \ | +| | | Clause 11.2.7 Delete Temporal Evolution of an Entity | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Temporal Context Source | Clause 11.3.2 Retrieve Temporal Evolution of an Entity \ | Clause 12.2.2 Register Context Source \ | +| | Clause 11.3.3 Query Temporal Evolution of Entities | Clause 12.2.3 Update CSR \ | +| | | Clause 12.2.4 Delete CSR | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Temporal Context Repository | Clause 11.2.2 Upsert Temporal Evolution of an Entity \ | none | +| | Clause 11.2.3 Add Attributes to Temporal Evolution of an Entity \ | | +| | Clause 11.2.4 Delete Attributes from Temporal Evolution of an Entity \ | | +| | Clause 11.2.5 Partial Update Attribute instance \ | | +| | Clause 11.2.6 Delete Attribute Instance \ | | +| | Clause 11.2.7 Delete Temporal Evolution of an Entity | | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Context Registry | Clause 12.2.2 Register Context Source \ | Clause 12.4.7 CSR Notification | +| | Clause 12.2.3 Update CSR \ | | +| | Clause 12.2.4 Delete CSR \ | | +| | Clause 12.3.2 Retrieve CSR \ | | +| | Clause 12.3.3 Query CSRs \ | | +| | Clause 12.4.2 Create CSR Subscription \ | | +| | Clause 12.4.3 Update CSR Subscription \ | | +| | Clause 12.4.4 Retrieve CSR Subscription \ | | +| | Clause 12.4.5 Query CSR Subscription \ | | +| | Clause 12.4.6 Delete CSR Subscription | | ++--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +::: + + diff --git a/md/clause-7.md b/md/clause-7.md new file mode 100644 index 0000000000000000000000000000000000000000..fb7f4d59fd58f4d07923e88da7507f5af61566fc --- /dev/null +++ b/md/clause-7.md @@ -0,0 +1,2058 @@ +# 7 API functionality + +## 7.1 Introduction + +Clause+++root describes the functionality of the [Core API]{.HTML-Keyboard}. + +## 7.2 Filtering + +### 7.2.1 Introduction + +Clause 7.2 describes the syntax and operation all the various filtering +operations which are available within the [Core API]{.HTML-Keyboard} and +[Temporal API]{.HTML-Keyboard}. + +### 7.2.2 Entity Type selection language + +The NGSI-LD Entity Type Selection Language shall be supported by +implementations. It is intended to select only those Entities that have the +specified Entity Type(s), possibly among others. Entity Types are specified as a +disjunction of elements, where each element can either directly be an Entity +Type or a conjunction of multiple Entity Types. The logical operators are the +same as in the NGSI-LD Query Language specified in clause 7.2.3. As a +disjunction of Entity Types can also be seen as a list, and to be compatible +with previous versions of the NGSI-LD API, a comma can be used as an alternative +representation of the or operator. For logical and grouping parenthesis are +needed. + + + +```text +EntityTypes = OrEntityType *(orOp OrEntityType) ; OrEntityType|OrEntityType +OrEntityType = %x28 EntityType *(andOp EntityType) %x29 ; (EntityType;EntityType) +OrEntityType = EntityType ; EntityType +andOp = %x3B ; ; +orOp = %x7C / %x2C ; | , +``` + + + +[EntityType]{.HTML-Sample} is either a valid name as specified in clause 5.2.2.3 +or a URI. + + + +>>> [!tip] EXAMPLE 1: + +Entities of type Building or House: + +- [Building|House]{.HTML-Code} +- [Building,House]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +Entities of type Home and Vehicle: + +[(Home;Vehicle)]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +Entities of type (Home and Vehicle) or Motorhome: + +- [(Home;Vehicle)|Motorhome]{.HTML-Code} +- [(Home;Vehicle),Motorhome]{.HTML-Code} + +>>> + + + + + +>>> [!note] NOTE: + +The special characters [","]{.HTML-Code} , [";"]{.HTML-Code} , +["("]{.HTML-Code} and [")"]{.HTML-Code} used in the Entity Type Selection +Language are allowed characters in URIs. The use of short names is recommended. + +>>> + + + + +### 7.2.3 Query Language + +#### 7.2.3.1 Introduction + +The NGSI-LD Query Language shall be supported by implementations. It is intended +to: + +- filter out Entities by Attribute Values (target is the _`value`_ member of a + _Property_, see Table 5.2.5-1, or the _`object`_ member of a Relationship, see + Table 5.2.6-1); +- filter out [Context Sources]{.HTML-Keyboard} by the values of properties that + describe them, defined when [Context Sources]{.HTML-Keyboard} are registered + (target is the name of a [Context Source]{.HTML-Keyboard} Property member of + the CSourceRegistration, see Table 5.2.9-1). +- filter out [Snapshots]{.HTML-Keyboard} by the values of the Snapshot data type + members, i.e. when filtering [Snapshots]{.HTML-Keyboard}, only the names of + the members defined for Snapshot in Table 5.2.43-1 are allowed values for + [AttrName]{.HTML-Sample}. + +#### 7.2.3.2 Query Language Definition + +Three string parameters are defined in order to fully specify an NGSI-LD Query: + +- _`q`_, to express the desired query; +- _`expandValues`_, to define the list of attributes whose values should be + expanded against the supplied _`@context`_ using JSON-LD type coercion prior + to executing the query in the [Context Broker]{.HTML-Keyboard}. + +**Optional** + +- _`jsonKeys`_, to define the list of attributes whose values uninterpretable as + JSON-LD and should not be expanded against the supplied _`@context`_ using + JSON-LD type coercion prior to executing the query in the [Context + Broker]{.HTML-Keyboard}. Optional + +In case of HTTP binding, whenever the string acting as a filter is part of the +HTTP binding's URI, then it shall be URI-encoded (percent-encoded, as described +in IETF RFC 3986 [n.18]). + +The grammar that encodes the syntax of the _`q`_ parameter, expressed in ABNF +format [n.16], is the NGSI-LD Query Language. It is described below (it has been +validated using [),]{.Hyperlink} and it shall +be supported by implementations: + + + +```text +Query = (QueryTerm / QueryTermAssoc) *(LogicalOp (QueryTerm / +QueryTermAssoc)) +QueryTermAssoc = %x28 QueryTerm *(LogicalOp QueryTerm) %x29 ; (QueryTerm) +QueryTerm = Attribute +QueryTerm =/ Attribute Operator ComparableValue +QueryTerm =/ Attribute equal CompEqualityValue +QueryTerm =/ Attribute unequal CompEqualityValue +QueryTerm =/ Attribute patternOp RegExp +QueryTerm =/ Attribute notPatternOp RegExp +Attribute = LinkedEntityRelation +LinkedEntityRelation = AttrName %x7B LinkedEntityPath %x7D ; AttrName{LinkedEntityPath} +LinkedEntityRelation =/ ValuePath +LinkedEntityPath = *1(EntityType 1*(%x2C EntityType) %x3A) AttrName %x7B +LinkedEntityPath %x7D ;*1(EntityType 1*(,EntityType):)AttrName{LinkedEntityPath} +LinkedEntityPath =/ ValuePath +ValuePath = DottedPath *1(%x5B DottedPath %x5D) ; DottedPath +*1([DottedPath]) +DottedPath = AttrName *(%x2E AttrName) ; AttrName *(.AttrName) +Operator = equal / unequal / greaterEq / greater / lessEq / less +ComparableValue = Number / quotedStr / dateTime / date / time +OtherValue = false / true +Value = ComparableValue / OtherValue +Range = ComparableValue dots ComparableValue +ValueList = Value 1*(%x2C Value) ; Value 1*(, Value) +CompEqualityValue = OtherValue / ValueList / Range / URI +equal = %x3D %x3D ; == +unequal = %x21 %x3D ; != +greater = %x3E ; > +greaterEq = %x3E %x3D ; >= +less = %x3C ; < +lessEq = %x3C %x3D ; <= +patternOp = %x7E %x3D ; ~= +notPatternOp = %x21 %x7E %x3D ; !~= +dots = %x2E %x2E ; .. +TermChar = unicodeNumber / unicodeLetter +TermChar =/ %x5F ; _ +AttrName = unicodeLetter *TermChar +EntityType = unicodeLetter *TermChar +quotedStr = String ; "*char" +andOp = %x3B ; ; +orOp = %x7C ; | +LogicalOp = andOp / orOp +``` + + + +- [unicodeNumber]{.HTML-Sample} is any Unicode character that has Number as a + Category [n.2]. With Unicode-capable regular expression (RegEx) parsers, such + a character may be matched by \\p{N}. +- [unicodeLetter]{.HTML-Sample} is any Unicode character that has Letter as a + Category [n.2]. With Unicode-capable regular expression (RegEx) parsers, such + a character may be matched by \\p{L}. +- [Number]{.HTML-Sample} shall be a number as mandated by the JSON + Specification, following the ABNF Grammar, production rule named + [number]{.HTML-Sample}, section 6 of IETF RFC 8259 [n.3]. +- [String]{.HTML-Sample} shall be a text string as mandated by the JSON + Specification, following the ABNF Grammar, production rule named + [String]{.HTML-Sample}, section 7 of IETF RFC 8259 [n.3]. +- [char]{.HTML-Sample} shall be a character as mandated by the JSON + Specification, ABNF Grammar, production rule named [char]{.HTML-Sample}, + section 7 of IETF RFC 8259 [n.3]. +- [false]{.HTML-Sample} shall be conformant with the JSON ABNF Grammar, + production rule named [false]{.HTML-Sample}, section 3 of IETF RFC 8259 [n.3]. + It is intended to represent the Boolean value corresponding to _`false`_. +- [true]{.HTML-Sample} shall be conformant with the JSON ABNF Grammar, + production rule named [true]{.HTML-Sample}, section 3 of IETF RFC 8259 [n.3]. + It is intended to represent the Boolean value corresponding to _`true`_. +- [RegExp]{.HTML-Sample} shall be a regular expression as mandated by IEEE + 1003.2™ [n.13]. +- [dateTime]{.HTML-Sample} shall be a _DateTime_ value as mandated by clause + 5.2.2.4. +- [time]{.HTML-Sample} shall be a _Time_ value as mandated by clause 5.2.2.4. +- [date]{.HTML-Sample} shall be a _Date_ value as mandated by clause 5.2.2.4. +- [URI]{.HTML-Sample} shall be a URI as mandated by IETF RFC 3986 [n.18] or an + IRI as mandated by IETF RFC 3987 [n.1], appendix A, production rule named URI. + +A **Query Term** (production rule [QueryTerm]{.HTML-Sample}) defines a predicate +which serves as a matching condition for Entities. The constituent parts of a +Query Term are: + +- an attribute path (production rule named [Attribute]{.HTML-Sample}). +- an optional pair composed by an operator (production rule named + [Operator]{.HTML-Sample}) and a value (production rule named + [Value]{.HTML-Sample}). + +The attribute path (production rule [Attribute]{.HTML-Sample}) is a simple name +[AttrName]{.HTML-Sample}, optionally followed by a dot-separated list of more +[AttrName]{.HTML-Sample} (see later example 8), optionally followed by one +trailing list of more dot-separated [AttrNames]{.HTML-Sample} enclosed in one +pair of square brackets (see later example 9). The attribute path is always a +composition of short hand names and not a fully qualified ones, because, when +the query language is used, an _`@context`_ properly defining all the terms (as +per clause 8.2.4) shall be issued. + + + +>>> [!tip] EXAMPLE 1: + +[?q=temperature]{.HTML-Code} + +Checks for the existence of the attribute _`temperature`_. + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +[?q=temperature==20]{.HTML-Code} + +Checks for entities whose _`temperature`_ Attribute +equals [20]{.HTML-Code}. See clause 7.2.3.4 for the definition of equality. + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +[?q=brandName!="Mercedes"]{.HTML-Code} + +Checks for entities whose _`brandName`_ Attribute does not equal ["Mercedes"]{.HTML-Code}. + +>>> + + + + + +>>> [!tip] EXAMPLE 4: + +[?q=isParked=="urn:ngsi-ld:OffStreetParking:Downtown1"]{.HTML-Code}. + +Checks for entities whose _`isParked`_ Attribute equals the given URI. + +>>> + + + + + +>>> [!tip] EXAMPLE 5: + +A query encoded as an HTTP Query String. Note that this is HTTP binding specific, +to be used via GET method. The NGSI-LD query language +string is conveyed by means of parameter _`q`_. + +[?q=speed>50;brandName!="Vauxhall%20Viva"]{.HTML-Code}. Also note that (as stated above) URI-encoding +(percent-encoding) is required if the query string contains reserved characters (see IETF +RFC 3986 [5] and IETF RFC 3987 [23], for the exact list of them). + +>>> + + + + + +>>> [!tip] EXAMPLE 6: + +[?q=isMonitoredBy]{.HTML-Code} + +To query for Entities that have the Attribute _`isMonitoredBy`_ ). + +>>> + + + + + +Query Terms may be combined through logical operators that shall be supported by implementations as follows: + +- The production rule [andOp]{.HTML-Sample} defines a logical AND operator conveying that the requested entities are those which meet at the same time the conditions posed by all the Query Terms affected by such an operator. +- The production rule [orOp]{.HTML-Sample} defines a logical OR operator conveying that the requested entities are those which meet any of the conditions posed by the Query Terms affected by such an operator. +- When evaluating logical conditions, and in the absence of specific Query Term associations (see below), the logical AND operator shall take precedence over the logical OR operator. + +Association of Query Terms shall be supported by implementations as per the grammar included by the present clause (production rule named QueryTermAssoc). An association of Query Terms is composed of the combination of different Query Terms linked by logical operators (AND, OR) and delimited by parenthesis. The evaluation of an association of Query Terms shall always take precedence over individual, non-associated Query Terms. + +>>> [!tip] EXAMPLE 7: + +[?q=((speed>50|rpm>3000);brandName=="Mercedes")]{.HTML-Code} + +Checks for entities whose _`speed`_ is greater than [20]{.HTML-Code} +**or** _`rpm`_ is greater than [3000]{.HTML-Code} **and** +whose _`brandName`_ Attribute equals ["Mercedes"]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 8: + +[?q=(temperature>=20;temperature<=25)|capacity<=10]{.HTML-Code} + +Checks for entities whose _`temperature`_ is equal to or greater than [20]{.HTML-Code} +**and** equal to or less than [25]{.HTML-Code} **or** +whose _`capacity`_ is equal to or less than [10]{.HTML-Code} + +>>> + + + +The following example shows the syntax of an attribute path that is defined by +the production rule Attribute, as a dot-separated list of names. Such a list is +intended to address a _Property_ or _Relationship_ included by the matching +entities subjacent graph, in accordance with the following rules: + +- Every name in the list shall be expanded to a URI (Fully Qualified Name) as + mandated by clause 8.2.4. +- The first name shall refer to a _Property_ or _Relationship_ (top level + element) whose subject shall be a matching Entity. Strictly speaking, and as + per the JSON-LD representation rules, such (fully qualified) name shall be + equal to the (fully qualified) name of the concerned _Property_ or + _Relationship_. +- Each other name (if present) represents a (sub)Property or (sub)Relationship, + starting with the top-level element as subject and continuing through the + graph traversal. The element addressed by the last name in the list is defined + as the target element. If only one name is present in the attribute path, then + the target element is the top level one. + + + +>>> [!tip] EXAMPLE 9: + +[?q=temperature.observedAt>=2017-12-24T12:00:00Z]{.HTML-Code} + +Checks for entities whose _`temperature`_ Attribute has an _`observedAt`_ Property +that matches or exceeds the given _DateTime_. + +>>> + + + +If the target element is a _Property_, the **target value** is defined as the +Value associated to such Property. If a Property has multiple instances +(identified by its respective _`datasetId`_), and no _`datasetId`_ is explicitly +addressed, the target value shall be any Value of such instances. + +If the target element is a _LanguageProperty_, and no target language is +specified, the **target value** is defined as a value from any of the key-value +pairs held within the _`languageMap`_ associated to such LanguageProperty. + +If the target element is a _ListProperty_, the **target value** is defined as +the _`valueList`_ array associated to such a _ListProperty_. + +If the target element is a _LanguageProperty_ and a target language is +specified, the **target value** is defined as the Value associated to the +matching key-value pair held within the _`languageMap`_ associated to such +LanguageProperty where the key matches the target language. + +If the target element is a _VocabProperty_, the **target value** shall be +expanded according to the _`@context`_. + +If the target element is a _Relationship_, the **target object** is defined as +the _`object`_ associated (represented as a URI or array of URIs) to such +Relationship. If a _Relationship_ has multiple instances (identified by its +respective _`datasetId`_), and no _`datasetId`_ is explicitly addressed, the +target object shall be any object of such instances. + +If the target element is a _ListRelationship_, the **target object** is defined +as the array of _`objects`_ associated (represented as URIs) to such +_ListRelationship_. + +When a Query Term only defines an attribute path (production rule named +[Attribute]{.HTML-Sample}), the matching Entities shall be those which define +the target element (_Property_ or a _Relationship_), regardless of any target +value or object. + +Lastly, implementations shall support queries involving specific data subitems +belonging to a Property Value (**seed target value**) represented by a JSON +object structure (compound value). For that purpose, an attribute path may +additionally contain a **trailing path** (enclosed in a single pair of square +brackets that signal that the overall path is now entering the compound value) +composed of a dot-concatenated list of JSON member names, and intended to +address a specific data subitem (member) within the **seed target value.** When +such a trailing path is present, implementations shall interpret and evaluate it +(against the seed target value) as a MemberExpression of ECMA 262 [n.19], in dot +notation, as clarified therein at section Property Accessors). If the evaluation +of such MemberExpression does not result in a defined value, the target element +shall be considered as non-existent for the purpose of query resolution. + + + +>>> [!tip] EXAMPLE 10: + +[?q=address[​city]=="Berlin"]{.HTML-Code}. + +Checks for entities whose _`address`_ Attribute holds a JSON Object containing the +attribute _`city`_ that equals the value ["Berlin"]{.HTML-Code} + +The trailing path +is [[​city]]{.HTML-Code}. It is used to refer to a particular subitem +within the value of the _`address`_ _Property_ , which is a complex JSON object +representing a postal address. Refer to the following NGSI-LD Entity: + +``` json +{ + "id": "urn:ngsi-ld:placedescription:123", + "type": "PlaceDescription", + "address": { + "type": "Property", + "value": { + "city": "Berlin", + "street": "Ulrich Strasse" + } + } +} +``` + + +>>> + + + + + +>>> [!tip] EXAMPLE 11: + +[?q=sensor.rawdata[​airquality.particulate]==40]{.HTML-Code}. + +Checks for entities whose _`sensor`_ Attribute holds a _Property_ of a _Property_ +called _`rawData`_. _`rawData`_ holds a JSON Object with the attribute _`airquality`_ +which in turn holds a sub-attibute called _`particulate`_ whose value is equal to +[40]{.HTML-Code} + + +The trailing path is [[​airquality.particulate]]{.HTML-Code}. +The _`particulate`_ _Property_ of the compound JSON object is targeted. +Refer to the following NGSI-LD Entity: + +``` json +{ + "id": "urn:ngsi-ld:particulatemeasurement:345", + "type": "ParticulateMeasurement", + "sensor": { + "type": "Property", + "value": 40, + "rawdata": { + "type": "Property", + "value": { + "airquality": { + "particulate": 40, + "PM20": 85 + } + } + } + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 12: + +[?q=parkingTickets[​value]=="Overstay 60 minutes"&jsonKeys=parkingTickets]{.HTML-Code}. + +Checks for entities whose _`parkingTickets`_ _JsonProperty_ holds a sub-attribute called _`value`_ +which equals ["Overstay 60 minutes"]{.HTML-Code}. + +The trailing path is [parkingTickets]{.HTML-Code}. +The [parkingTickets]{.HTML-Code} _Property_ of the JSON object is targeted, +but the target [value]{.HTML-Code} raw is JSON, which is not expanded to +[ngsi-ld:hasValue]{.HTML-Code} using the core _`@context`_. +Refer to the following NGSI-LD Entity: + +``` json +{ + "id": "urn:ngsi-ld:Car:6152s", + "type": "Car", + "parkingTickets": { + "type": "JsonProperty", + "json": { + "id": "85a6cc52-0589-45f9", + "value": "Overstay 60 minutes" + } + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 13: + +[?q=gender==Male&expandValues=gender]{.HTML-Code}. + +Checks for entities whose _`gender`_ _VocabProperty_ compacts down to ["Male"]{.HTML-Code} +when the supplied _`@context`_ is applied. + +The trailing +path is [gender]{.HTML-Code}. The _`gender`_ _Property_ of JSON object +is targeted, but the target value is first expanded to a URI using the +supplied _`@context`_. Refer to the following NGSI-LD Entity: + +``` json +{ + "id": "urn:ngsi-ld:Person:678", + "type": "Person", + "gender": { + "type": "VocabProperty", + "vocab": "Male", + } + }, + "@context": { + "Male": "http://example.org/Male", + } +} +``` + +>>> + + + +The filter can also apply to a _Property_ or _Relationship_ of an NGSI-LD Entity +targeted by a (recursively) followed _Relationship_, for example as part of a +[Linked Entity]{.HTML-Keyboard} retrieval (clause 7.7). + + + +>>> [!tip] EXAMPLE 14: + +[?q=sensor{humidity}==40]{.HTML-Code}. + +Checks for entities with a _`sensor`_ _Relationship_ where the target object +has a _`humidity`_ Attribute whose value equals [40]{.HTML-Code}. + +The trailing path is +[sensor{humidity}]{.HTML-Code}. The query targets entities with a _`sensor`_ +_Relationship_ and makes a sub-query on matching target objects which have the +matching _`humidity`_ Attribute. Refer to the following NGSI-LD Entities: + +``` json +{ + "id": "urn:ngsi-ld:WeatherStation:123", + "type": "WeatherStation", + "sensor": { + "type": "Relationship", + "objectType": "Device", + "object": "urn:ngsi-ld:Device:345" + } +} +{ + "id": "urn:ngsi-ld:Device:345", + "type": "Device", + "humidity": { + "type": "Property", + "value": 40 + } +} +``` + +>>> + + + +As not knowing the Entity Type targeted by a _Relationship_ could make the query +significantly more expensive, a hint for the required Entity Type can be +provided, so only such NGSI-LD Entities need to be considered. + + + +>>> [!tip] EXAMPLE 15: + +[?q=sensor{Device:humidity}==40]{.HTML-Code}. The trailing path is +[sensor{Device:humidity}]{.HTML-Code}. + +Checks for entities with a _`sensor`_ _Relationship_ where the target object +of type ["Device"]{.HTML-Code} has a _`humidity`_ Attribute whose value equals [40]{.HTML-Code}. + +The query targets entities with a +[sensor.entityType = "Device"]{.HTML-Code} within a _Relationship_ and then +makes a sub-query on matching target _`objects`_ which have the +matching _`humidity`_ Attribute. The _`entityType`_ hint results in a faster lookup. +Refer to the following NGSI-LD Entities. + +``` json +{ + "id": "urn:ngsi-ld:WeatherStation:123", + "type": "WeatherStation", + "sensor": { + "type": "Relationship", + "objectType": "Device", + "object": "urn:ngsi-ld:Device:345" + } +} +{ + "id": "urn:ngsi-ld:Device:345", + "type": "Device", + "humidity": { + "type": "Property", + "value": 40 + } +} +``` + +>>> + + + +If the target element corresponds to a _Relationship_ or _ListRelationship_, the +combination of such target element with any operator different than equal or +unequal shall result in **not matching**. + +#### 7.2.3.3 Query Terms and Logical Operators + +A **Query Term value** shall be any of the following (depending on the operator +used): + +- A literal value (string, number, date, etc.) (production rule named + [Value]{.HTML-Sample}). +- A range of values (production rule named [Range]{.HTML-Sample}), specified as + a minimum and a maximum value. +- A regular expression (production rule named [RegExp]{.HTML-Sample}). +- A URI (production rule named [URI]{.HTML-Sample}). +- A comma-separated list of literal values (production rule named + [ValueList]{.HTML-Sample}). + +When comparing dates or times, the order relation considered shall be a temporal +one. + +When it comes to comparing text strings, implementations: + +- shall follow the recommendations defined by IETF RFC 8259 [n.3], section 8.3. +- should support the Unicode Collation Algorithm (UCA), as defined by [n.20]. + +URI comparison should be performed so that the number of false negatives is +minimized, as recommended by IETF RFC 3986 [n.18], section 6. + +The semantics of the different **logical operators** used by Query Terms are +described as follows and shall be supported by compliant implementations: + +- **Existence** (only attribute is specified). A matching entity shall contain + the target element. + +- **Equal** operator (production rule named [equal]{.HTML-Sample}). A matching + Entity shall contain the target element and meet at least one of the + conditions defined in clause 7.2.3.4 + +- **Unequal** operator (production rule named [unequal]{.HTML-Sample}). A + matching entity shall contain the target element and meet none of the + conditions defined in clause 7.2.3.4 + - If the data type of the target value and the data type of the Query Term + value are different, then they shall be considered unequal. + +- **Greater than** operator (production rule named [greater]{.HTML-Sample}). For + an entity to match, it shall contain the target element and the target value + has to be strictly greater than the Query Term value: + - If there is no equality between the target value data type and the Query + Term value data type then it shall be considered as not matching. + +- **Less than** operator (production rule named [less]{.HTML-Sample}). For an + entity to match, it shall contain the target element and the target value + shall be strictly less than the value: + - If there is no equality between the target value data type and the Query + Term value data type then it shall be considered as not matching. + +- **Greater or equal than** (production rule named [greaterEq]{.HTML-Sample}). A + matching entity shall meet any of the _Greater than_ or the Equal conditions + for single values. + +- **Less or equal than** (production rule named [lessEq]{.HTML-Sample}). A + matching entity shall meet any of the _Less than_ or the Equal conditions for + single values. + +- **Match pattern** (production rule named [patternOp]{.HTML-Sample}). A + matching entity shall contain the target element and the target value shall be + in the L(R) of the regular pattern specified by the Query Term: + - If the target value data type is different than _String_ then it shall be + considered as not matching. + +- **Do not match pattern** (production rule named [notPatternOp]{.HTML-Sample}). + A matching entity shall contain the target element and the target value shall + not be in the L(R) of the regular pattern specified by the Query Term: + - If the target value data type is different than _String_ then it shall be + considered as not matching. + +#### 7.2.3.4 Query Term Equality + +A target value shall be considered equal to a query term if any of the following +conditions apply: + +1. The Query Term value: + - Is identical or equivalent to the target value. + - Is included in the target value, and the latter is an array. + + + +>>> [!tip] EXAMPLE 1: + +The Query Term value, [color=="red"]{.HTML-Code}: + +- Matches ["red"]{.HTML-Code} as it is identical or equivalent to the target + value. + +- Matches [["blue","red","green"]]{.HTML-Code} as the element + ["red"]{.HTML-Code} is included in an array. + +>>> + + + +2. The Query Term value is a list of values (production rule named + [ValueList]{.HTML-Sample}) and: + - The target value is identical or equivalent to any of the list values + - The target value includes any of the Query Term values, and the target + value is an array + + + +>>> [!tip] EXAMPLE 2: + +The Query Term value, [color=="black","red"]{.HTML-Code}: + +- Matches ["red"]{.HTML-Code} as it is identical or equivalent to one of the + list values + +- Matches [["red","blue"]]{.HTML-Code} as the target value includes + one of the Query Term values + +>>> + + + +3. The Query Term value is a range (production rule named + [Range]{.HTML-Sample}), and: + - The target value is in the interval between the minimum and maximum of the + range (both included) + + + +>>> [!tip] EXAMPLE 3: + +The Query Term value, [temperature==10..20]{.HTML-Code}: + +- Matches [15]{.HTML-Code} as it lies between 10 and 20. + +>>> + + + +4. The Query Term value target element corresponds to a _LanguageProperty_ and a + natural language is specified and: + - a match is found as the value of the key-value pair corresponding to the + specified natural language of the _`languageMap`_. + - a match is found as a single element from the array of values of the + key-value pair corresponding to the specified natural language of the + _`languageMap`_. + + + +>>> [!tip] EXAMPLE 4: + +The Query Term value, [description[​fr]=="pain"]{.HTML-Code} + +- Matches to the _`languageMap`_ below as the value + ["pain"]{.HTML-Code} corresponds to the key ["fr"]{.HTML-Code} + +```json +{ + "de": "Brot", + "en": "bread", + "fr": "pain" +} +``` + +- Does not match to the _`languageMap`_ below as the value + ["pain"]{.HTML-Code}, although present in the _`languageMap`_, + does not correspond to the key ["fr"]{.HTML-Code} + +```json +{ + "de": "Schmerz", + "en": "pain", + "fr": "douleur" +} +``` + +- Matches to the _`languageMap`_ below as the value + ["pain"]{.HTML-Code} corresponds an element withn the key + ["fr"]{.HTML-Code} + +```json +{ + "de": ["Brot", "Käse"], + "en": ["bread", "cheese"], + "fr": ["pain", "fromage"] +} +``` + +- Does not match to the _`languageMap`_ below as the value + ["pain"]{.HTML-Code} does not correspond to an element within the key + ["fr"]{.HTML-Code} + +```json +{ + "de": ["Vergnügen", "Schmerz"], + "en": ["pleasure", "pain"], + "fr": ["plaisir", "douleur"] +} +``` + +>>> + + + +5. The Query Term value target element corresponds to a _LanguageProperty_ and + no natural language is specified and: + - a match is found in any of the values of the key-value pairs of the + _`languageMap`_ + - a match is found as a single element within the arrays of values of the + key-value pairs of the _`languageMap`_ + + + +>>> [!tip] EXAMPLE 5: + +The Query Term value, [description[\*]=="pain"]{.HTML-Code} + +- Matches to the _`languageMap`_ below as the value ["pain"]{.HTML-Code} can be found. + +```json +{ + "de": "Brot", + "en": "bread", + "fr": "pain" +} +``` + +- Also Matches to the _`languageMap`_ below as the value ["pain"]{.HTML-Code} can be found + as an element of an array. + +```json +{ + "de": ["Vergnügen", "Schmerz"], + "en": ["pleasure", "pain"], + "fr": ["plaisir", "douleur"] +} +``` + +>>> + + + +6. The Query Term value is a URI and the target element corresponds to a + _Relationship_ , a _ListRelationship_ or a _VocabProperty_ and: + - Is identical to the target value + - Is included in the target value, if the latter is an array + + + +>>> [!tip] EXAMPLE 6: + +The Query Term value, [color=="http://example/red"]{.HTML-Code} + +- Matches to the _`object`_ below as it is identical or equivalent to the target value. + +```json +"http://example.com/red" +``` + +- Matches to the _`objectList`_ below as it is included in the array + +```json +[ + "http://example.com/red" +] +``` + +- Matches to the _`objectList`_ below as the element ["http://example.com/red"]{.HTML-Code} + is included in the array + +```json +[ + "http://example.com/blue", + "http://example.com/red", + "http://example.com/green" +] +``` + +>>> + + + +7. If the Query Term value target element corresponds to a _Relationship_, a + _ListRelationship_ or a _VocabProperty_ and is a list of URIs (production + rule named ValueList) + + - The target value is identical to any of the list values. + - The target value includes any of the Query Term values, if the target + value is an array. + + + +>>> [!tip] EXAMPLE 7: + +The Query Term value, [color=="http://example/black","http://example/red"]{.HTML-Code} + +- Matches to the _`object`_ below as it is identical or equivalent to one of the list values + +```json +"http://example.com/red" +``` + +- Matches to the _`object`_ below as the element ["http://example.com/red"]{.HTML-Code} + is included as one of the elements within the array. + +```json +[ + "http://example.com/blue", + "http://example.com/red", + "http://example.com/green" +] +``` + +>>> + + + + +8. If there is no equality between the target value data type and the Query + Term value data type, then it shall be considered as not matching. + + +### 7.2.4 GeoQuery language + +The NGSI-LD Geoquery language shall be supported by implementations. It is +intended to define predicates which allow testing whether a specific topological +spatial relationship exists between a pair of geometries: a target geometry and +a reference geometry. The target geometry represents a geospatial Property of an +Entity, typically, the location of the Entity. + +A total of four parameters are defined in order to fully specify an NGSI-LD +Geoquery: + +- _`georel`_, to express the desired geospatial relationship; +- _`geometry`_, to express the type of the reference geometry; +- _`coordinates`_, to express the reference geometry; +- _`geoproperty`_, to express the target geometry of an Entity. This parameter + is optional, location is the default. + +The following grammar defines the syntax for the geospatial relationships +(parameter name _`georel`_): + + + +```text +andOp = %x3B ; ; +equal = %x3D %x3D ; == +georel = nearRel / withinRel / containsRel / overlapsRel / intersectsRel / equalsRel / disjointRel +nearRel = nearOp andOp distance equal PositiveNumber ; near;max(min)Distance==x (in meters) +distance = "maxDistance" / "minDistance" +nearOp = "near" +withinRel = "within" +containsRel = "contains" +intersectsRel = "intersects" +equalsRel = "equals" +disjointRel = "disjoint" +overlapsRel = "overlaps +``` + + + +[PositiveNumber]{.HTML-Sample} shall be a non-zero positive number as mandated +by the JSON Specification. Thus, it shall follow the ABNF Grammar, production +rule named [Number]{.HTML-Sample}, section 6 of IETF RFC 8259 [n.3], excluding +the 'minus' symbol and excluding the number 0. + +Reference geometries shall be specified by: + +- A geometry type (parameter name _`geometry`_) as defined by the GeoJSON + specification (IETF RFC 7946 [n.4], section 1.4), except _GeometryCollection_. +- A coordinates (parameter name _`coordinates`_) element which shall represent + the coordinates of the reference geometry as mandated by IETF RFC 7946 [n.4], + section 3.1.1. + +Target geometry, i.e. the target Entity's _GeoProperty_ to which the geoquery is +to be applied, can be specified by an extra parameter named _`geoproperty`_. The +_GeoProperty's_ name shall be specified as short hand name and not a fully +qualified one, because, when the query language is used, an _`@context`_ +properly defining all the terms (as per clause 8.2.4) shall be issued. If no +_`geoproperty`_ is specified, the geoquery is applied to the default +_GeoProperty_ _`location`_ (see clause 5.2.6.4.5). + +Note that proper URL encoding shall be used by HTTP binding API clients when +using these examples. + + + +>>> [!tip] EXAMPLE 1: + +``` text +?georel=near;maxDistance==2000 +&geometry=Point +&coordinates=[8,40] +&geoproperty=observationSpace +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +``` text +?georel=within +&geometry=Polygon +&coordinates=[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0], +[100.0,0.0]]] +&geoproperty=location +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +A query encoded as an HTTP Query String. Note that this is HTTP binding +specific, to be used via GET method, as defined in clause 6.4.3.2. + +``` text +?georel=near;maxDistance==2000 +&geometry=Point +&coordinates=[8,40] +``` + +>>> + + + +The semantics of the different geospatial relationships defined above is as +follows, and shall be supported by compliant implementations: + +- **near** statement (production rule named [nearRel]{.HTML-Sample}): + - [maxDistance]{.HTML-Sample} modifier. For an entity to match it has to be + within the buffer geometric object (as defined by [n.21]) given by the + reference geometry, with distance (in meters) equal to the number conveyed + (production rule named [PositiveNumber]{.HTML-Sample}). + - [minDistance]{.HTML-Sample} modifier. For an entity to match it has to be + disjoint with the buffer geometric object (as defined by [n.21]) given by + the reference geometry, with distance (in meters) equal to the number + conveyed (production rule named [PositiveNumber]{.HTML-Sample}). + +- **equals** relationship (production rule named [equalsRel]{.HTML-Sample}). For + an entity to match, the target geometry shall be equal, as specified by + [n.21], to the reference geometry. +- **disjoint** relationship (production rule named [disjointRel]{.HTML-Sample}). + For an entity to match, the target geometry shall be disjoint, as specified by + [n.21], to the reference geometry. +- **intersects** relationship (production rule named + [intersectsRel]{.HTML-Sample}). For an entity to match, the target geometry + shall intersect, as specified by [n.21], with the reference geometry. +- **within** relationship (production rule named withinRel). For an entity to + match, the target geometry shall be within, as specified by [n.21], the + reference geometry. +- **contains** relationship (production rule named [containsRel]{.HTML-Sample}). + For an entity to match, the target geometry shall contain, as specified by + [n.21], the reference geometry. +- **overlaps** relationship (production rule named [overlapsRel]{.HTML-Sample}). + For an entity to match, the target geometry shall overlap, as specified by + [n.21], the reference geometry. + +When resolving geo-queries, Entities which do not convey the target +_GeoProperty_ of the query shall be considered as non-matching. + +### 7.2.5 Scope query language + +The NGSI-LD Scope Query Language shall be supported by implementations. It is +intended to select only those Entities that are within the specified Scope(s). +Scopes are specified as a disjunction of elements, where each element can either +directly be a Scope or a conjunction of multiple Scopes. The ["+"]{.HTML-Code} +can be used as a wildcard to match a single scope level within a Scope. The +["#"]{.HTML-Code} that can be added at the end of a Scope specification serves +as a wildcard, which matches the given scope and the whole hierarchy of scopes +below. The ["/#"]{.HTML-Code} matches any non-empty scope, i.e. only explicitly +specified scopes. The logical operators are the same as in the NGSI-LD Query +Language specified in clause 7.2.3. As a disjunction of Scopes can also be seen +as a list, a comma can be used as an alternative representation of the or +operator. For logical and grouping parenthesis are needed. + + + +```text +ScopesQ = OrScopeQ *(orOp OrScopeQ) ; OrScopeQ|OrScopeQ +ScopesQ =/ %x2F %23 ; / # +OrScopeQ = %x28 ScopeQ *(andOp ScopeQ) %x29 ; (ScopeQ;ScopeQ) +OrScopeQ =/ ScopeQ *1(%x2F %23) ; ScopeQ / # +andOp = %x3B ; ; +orOp = %x7C / %x2C ; | , +ScopeQ = %x2F ScopeQLevel *(%x2F ScopeQLevel) ; /ScopeQLevel *(/ScopeQLevel) +ScopeQLevel = unicodeLetter *ScopeQLevelChar +ScopeQLevel =/ %x2B ; + +ScopeQLevelChar = unicodeNumber / unicodeLetter +ScopeQLevelChar =/ %x5F ; _ +``` + + + + + +>>> [!tip] EXAMPLE 1: + +Scope /Madrid: + +[/Madrid]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +Scope /Madrid/Gardens and the whole scope tree below: + +```text +/Madrid/Gardens/#, +/Madrid/Gardens, /Madrid/Gardens/ParqueNorte, /Madrid/Gardens/ParqueNorte/Parterre1, /Madrid/Gardens/ParqueSur +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +Scopes /Madrid/Gardens/ParqueNorte and /Madrid/Sights/ParqueNorte, or any other Scope with Madrid as first scope level and ParqueNorte as third scope level: + +[/Madrid/+/ParqueNorte]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 4: + +Scope /Madrid/Districts and /CompanyA: + +[(/Madrid/Districts;/CompanyA)]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 5: + +Scope (/Madrid/Districts and /CompanyA) or /CompanyB: + +[(/Madrid/Districts;/CompanyA)|CompanyB]{.HTML-Code} [(/Madrid/Districts;/CompanyA),CompanyB]{.HTML-Code} + +>>> + + + +### 7.2.6 Temporal query language + +The NGSI-LD Temporal Query language shall be supported by implementations. It is +intended to define predicates which allow testing whether Temporal Properties of +NGSI-LD Entities, Properties and Relationships, are within certain temporal +constraints. In particular it can be used to request historic Property values +and Relationships that were valid within the specified timeframe. + +The following grammar defines the syntax that shall be supported: + + + +```text +timerel = beforeRel / afterRel / betweenRel +beforeRel = "before" +afterRel = "after" +betweenRel = "between" +``` + + + +The points in time for comparison are defined as follows: + +- A _`timeAt`_ parameter, which shall represent the comparison point for the + before and after relation and the starting point for the between relation. It + shall be represented as _DateTime_ (mandated by clause 5.2.2.4). +- An _`endTimeAt`_ parameter, which is only used for the between relation and + shall represent the end point for comparison. It shall be represented as + _DateTime_ (mandated by clause 5.2.2.4). + +The Temporal Property (see clause 5.2.4) to which the temporal query is to be +applied can be specified by _`timeproperty`_. If no _`timeproperty`_ is +specified, the temporal query is applied to the default Temporal Property +_`observedAt`_. + + + +>>> [!tip] EXAMPLE 1: + +[?timerel=before&timeAt=2017-12-13T14:20:00Z]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +[?timerel=between&timeAt=2017-12-13T14:20:00Z&endTimeAt=2017-12-13T14:40:00Z&timeproperty=modifiedAt]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +Temporal query encoded as HTTP Query String, note that this is HTTP binding +specific, to be used via GET method. + +```text +?timerel=between +&timeproperty=observedAt +&timeAt=2017-12-13T14:20:00Z +``` + +>>> + + + +The semantics of the different temporal relations defined above is as follows, +and shall be supported by compliant implementations: + +- **before** relationship (production rule named [beforeRel]{.HTML-Sample}). For + a Temporal Property to match, the value of the specified Temporal Property (or + _`observedAt`_ as default) has to be before the time specified by _`timeAt`_. + The specified value is used as an exclusive bound in the Temporal Query; +- **after** relationship (production rule named [afterRel]{.HTML-Sample}). For a + Temporal Property to match, the value of the specified Temporal Property (or + _`observedAt`_ as default) has to be after the time specified by _`timeAt`_. + The specified value is used as an inclusive bound in the Temporal Query; +- **between** relationship (production rule named [betweenRel]{.HTML-Sample}). + For a Temporal Property to match, the value of the specified Temporal Property + (or _`observedAt`_ as default) has to be after the time specified by + _`timeAt`_ and before the time specified by _`endTimeAt`_. In the Temporal + Query, the value specified for the lower bound of the range is inclusive and + the value specified for the upper bound of the range is exclusive. + +When resolving temporal queries, Entities which do not convey the target +Temporal Property of the query shall be considered as non-matching. + +### 7.2.7 Language filter + +The NGSI-LD Language Filter shall be supported by implementations. It is +intended to form a mechanism which allows just one matching string value of +_LanguageProperties_ of NGSI-LD Entities to be converted to an NGSI-LD Property, +where the value will be a string for the specified natural language. + +The following grammar defines the syntax that shall be supported by the filter: + +- [ lang = langtag]{.HTML-Code} + +Where the langtag is defined according to the rules as mandated by IETF RFC 5646 +[n.11], and IETF RFC 3282 [n.22]. If the [Context Broker]{.HTML-Keyboard} cannot +serve any matching language, it shall default to any supported language. This +behaviour can be triggered by specifying [lang="\*"]{.HTML-Code} in the filter +(see example 3). + +In any case, the attribute in question shall be augmented with an additional +non-reified subproperty _`lang`_ indicating the actual language returned. + + + +>>> [!tip] EXAMPLE 1: + +Specified natural language - return LanguageProperties as strings in English +only. + +[ lang="en"]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +Multiple natural languages with no ranked preference - return LanguageProperties +as strings in either Swiss French or French. + +[ lang="fr-CH,fr"]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +Wildcard - return LanguageProperties as a string in any supported language. + +[ lang="\*"]{.HTML-Code} + +>>> + + + + + +>>> [!tip] EXAMPLE 4: + +Quality value ranking - return all LanguageProperties as a string in Swiss +French or French with no ranked preference, fallback to English as a second +choice and finally fallback to any other supported language. + +[ lang="fr-CH,fr;q=0.9,en;q=0.8,\*;q=0.5"]{.HTML-Code} + +>>> + + + +## 7.3 Projection + +### 7.3.1 Introduction + +This clause describes the projection language of the [Core API]{.HTML-Keyboard} +and [Temporal API]{.HTML-Keyboard}, which allows clients to request payloads +which only contain specified Attributes from the selected Entities. + +### 7.3.2 Attribute projection language + +The NGSI-LD Attribute Projection Language shall be supported by implementations +for projection parameters (e.g. _`pick`_ and _`omit`_). Its aim is to specify +the Attributes to be retrieved within an Entity (or associated [Linked +Entities]{.HTML-Keyboard} when [Linked Entity]{.HTML-Keyboard} Retrieval is +used). Projected Attributes are specified as a disjunction of elements, where +each element can either directly be an Attribute name, or in the case of [Linked +Entity]{.HTML-Keyboard} Retrieval, a Relationship name followed by an Attribute +name within the [Linked Entity.]{.HTML-Keyboard} Since a disjunction of +Attributes is a list, either a comma or a pipe character can be used as +alternative representations of the or operator. In the following, ABNF grammar +for NGSI-LD Attribute Projection Language is given. + + + +```text +orOp = %x7C / %x2C ; | , +ProjectionTerm = AttrName *1(LinkedEntityTerm) *(orOp ProjectionTerm) +LinkedEntityTerm = %x7B ProjectionTerm %x7D ; {ProjectionTerm} +``` + + + +See clause 7.2.3 for the definition of [AttrName]{.HTML-Sample}. + + + +>>> [!tip] EXAMPLE 1: + +[?pick=temperature]{.HTML-Code} + +Return only the _`temperature`_ Attribute from selected Entities + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +[?omit=temperature]{.HTML-Code} + +Return the selected Entities and remove the _`temperature`_ Attribute from +each of the results. + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +[?pick=id,temperature,humidity]{.HTML-Code} + +Return only the Entity _`id`_ and _`temperature`_ and _`humidity`_ Attributes from selected Entities + +>>> + + + + + +>>> [!tip] EXAMPLE 4: + +[?pick=observation{temperature,humidity}]{.HTML-Code} + +Return only the _`temperature`_ and _`humidity`_ Attributes from the [Linked Entity]{.HTML-Keyboard} +corresponding to the target object of the _`observation`_ _Relationship_ found in the selected Entities + +>>> + + + +### 7.3.3 Attribute filtering (deprecated) + +Prior to the introduction of the projection parameters _`pick`_ and _`omit`_ +(see clause 7.3.2), the projection of Attributes was defined the using the +attribute filtering parameter _`attrs`_. + +The _`attrs`_ parameter, which can only be applied to named Attributes, +simualtaneously combines an existence check for an attribute +[?q=<​Attribute Name>]{.HTML-Code}, along with an associated pick +operation [?pick=<​Attribute Name>]{.HTML-Code}, whilst also +including the _`id`_ and _`type`_ in the response. + + + +>>> [!tip] EXAMPLE 1: + +[?attrs=temperature]{.HTML-Code} + +Checks for the existence of the attribute _`temperature`_, and +returns the _`id`_, _`type`_ and the _`temperature`_ Attribute from selected +Entities + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +[?attrs=temperature,humidity]{.HTML-Code} + +Checks for the existence of both the _`humidity`_ and _`temperature`_ Attributes, and +returns the _`id`_, _`type`_,and the _`humidity`_ and _`temperature`_ Attributes from +selected Entities + +>>> + + + +In the following, an ABNF grammar for NGSI-LD Attribute filtering is given. + + + +```text +andOp = %x2C ; , +FilteringTerm = AttrName *(andOp FilteringTerm) +``` + + + +See clause 7.2.3 for the definition of [AttrName]{.HTML-Sample}. + +For backwards compatibility reasons, [Context Broker]{.HTML-Keyboard} +implementations shall continue to support attribute filtering, although the +operation has been deprecated in favour of projection and existance parameters. + +## 7.4 Pagination + +### 7.4.1 Introduction + +This clause describes pagination operations within of the [Core +API]{.HTML-Keyboard} and [Temporal API]{.HTML-Keyboard}, which allows clients to +limit the number of items within a payload at to retrieve items at an offset. + +### 7.4.2 Pagination according to Elements + +#### 7.4.2.1 Introduction + +NGSI-LD operations can potentially return a result set including a large number +of NGSI-LD Elements, so that pagination of query results shall be supported by +compliant implementations. + +The list of operations that incur this behaviour is as follows: + +- Query Entities (clause 10.4.3). +- Query Subscriptions (clause 10.5.5). +- Query [Context Source Registrations]{.HTML-Keyboard} (clause 12.3.3). +- Query [Context Source Registration]{.HTML-Keyboard} Subscriptions (clause + 12.4.5). +- Query [Temporal Evolution of Entities]{.HTML-Keyboard} (clause 11.3.3). + +Nonetheless, the NGSI-LD API is agnostic about specific pagination mechanisms +and only defines the behaviour that shall be observed by NGSI-LD Systems. + +For each operation above, NGSI-LD Systems shall: + +- provide a mechanism to iterate through the NGSI-LD Elements of a result set + without exhausting NGSI-LD Client or Broker resources; +- provide a mechanism to flag NGSI-LD Clients when there are remaining NGSI-LD + Elements to be traversed as part of a result set; +- allow NGSI-LD Clients specifying a limit (page size), as a parameter of API + operations, to the number of NGSI-LD Elements (at a maximum) retrieved by the + implementation for each pagination iteration; +- define a **default limit** (default page size) to the number of NGSI-LD + Elements retrieved per pagination iteration; +- allow NGSI-LD Clients iterating forwards and backwards through a result set. + +NGSI-LD implementations should: + +- avoid Denial of Service attacks or other potential security risks, by defining + a hard limit to the size of generated response payload body while paginating. + For instance, certain queries can be rejected by issuing an error of type + [TooManyResults]{.HTML-Error}. + +NGSI-LD implementations may: + +- warn NGSI-LD Clients when result sets become invalid due to dynamic changes in + NGSI-LD Elements (additions, deletions) occurred while iterating over pages. + +The concrete realization of the features described above might depend on each +API binding. Nonetheless, NGSI-LD Systems shall implement pagination features as +mandated by the present clause, for any API binding. + +#### 7.4.2.2 General pagination behaviour + +When resolving NGSI-LD Query operations, NGSI-LD Systems shall exhibit the +behaviour described by the present clause: + +- Let **Md** be equal to the default maximum number of NGSI-LD Elements to be + retrieved by the API during each query pagination iteration, as defined by the + NGSI-LD implementation. +- Let **Mc** be equal to the maximum number of NGSI-LD Elements to be retrieved + as requested by the NGSI-LD Client. If **Mc** is undefined then it shall be + equal to **Md**. +- Let **L** be the maximum number of NGSI-LD Elements to be retrieved by the API + during each query pagination iteration. **L** shall be equal to **Mc**. +- During query execution and for each pagination iteration, the query resolution + mechanisms of the NGSI-LD System shall ensure that only up to a maximum of + **L** NGSI-LD Elements are retrieved and returned to the NGSI-LD client, i.e. + the maximum page size per iteration shall not overpass **L**. Nonetheless, + implementations shall take care of not overpassing a maximum size of response + payload body, which, in practice, implies that, under certain circumstances, + the number of Elements retrieved per page can be lower than **L**. +- After the retrieval of each page (containing at most **L NGSI-LD Elements**) + implementations shall check whether there are pending NGSI-LD Elements to be + retrieved in the context of the current query. If that is the case, + implementations shall flag NGSI-LD Clients of the existence of such NGSI-LD + Elements. Ultimately, the flagging mechanisms used shall depend on each API + binding but shall be present as mandated by the present clause. +- When flagging the existence of additional NGSI-LD Elements (pages) pending to + be retrieved, generally, implementations shall provide NGSI-LD Clients + pointers to get access to both the following page of NGSI-LD Elements and the + previous one, according to the current pagination iteration. +- The pointer to the previous page of NGSI-LD Elements shall be included for all + pagination iterations excepting the first one, as, obviously, there will be no + previous NGSI-LD Elements. +- When the last page of NGSI-LD Elements is reached, only the pointer to the + previous page shall be provided to NGSI-LD Clients, so that they can detect + that no more NGSI-LD Elements are available. +- The pointers to NGSI-LD Elements shall contain all the parameters needed to + allow NGSI-LD Clients to retrieve the next and previous page, without further + interactions with the API. + +While iterating over a set of pages, there might be changes in the target result +set, due to additions or removals of NGSI-LD Elements occurring in between. +Implementations may detect those situations and may warn NGSI-LD Clients +appropriately. During pagination, the same _`@context`_ shall be used. An +attempt to use a different _`@context`_ should result in an +**[BadRequestData]{.HTML-Keyboard}** error. + +#### 7.4.2.3 Pagination option using limit and offset + +The general pagination behaviour described in clause 7.4.2.2 only requires +pointers to the following and previous pages, which can be implemented in a +completely opaque way. Pagination may also be implemented in a transparent way, +giving the Context Consumer more control over the process. In this case, the +parameters _`limit`_ and _`offset`_ should be used, allowing the Context +Consumer to adapt the size of the page using _`limit`_ and jump to a desired set +of elements in the results using _`offset`_. + +#### 7.4.2.4 Pagination with Entity maps + +In the case of queries based on Entity maps, the set of Entities considered for +the result is fixed with the initial query creating the Entity map. However, the +Entity information itself can be dynamic, so filters shall be rechecked before +returning results. In the case of split Entities, the Entities in the Entity map +can only be considered as candidate Entities, since, at the time of Entity map +creation, the Entities have not been aggregated and thus the filters could not +be applied. This can only be done when preparing a page for pagination. Thus, +Entities not or no longer fitting the query shall be removed from the Entity map +during pagination. Pages shall always be filled to the maximum, as long as +Entities are available. When using the previous link, the set of Entities on the +previous page may not be the same as before, due to dynamic changes resulting in +Entities no longer fulfilling the filter criteria of the query. As a result, the +first page when going backward, and the last page, when going forward, may have +less than the maximum number of Entities. + +## 7.5 Counting results + +Given that NGSI-LD Query operations can potentially return a result set +including a large number of NGSI-LD Elements and that pagination of query +results shall be supported (see clause 7.4), compliant implementations shall +also support a mechanism for relaying to the client the number of expected +resulting elements, when a query is executed. + +A specific field (e.g. a custom header in the response in case of HTTP binding) +shall be returned within the response of a query, whenever this is requested by +the client. + +Mechanisms for limiting the number of returned NGSI-LD Elements are independent +of the counting mechanism, so that, potentially, a client can issue a query that +limits to zero the number of desired results but asks for the count to be +present. + +This is useful for client-side planning and fine-tuning of subsequent queries +and their parameters. + +## 7.6 Ordering + +### 7.6.1 Introduction + +This clause describes Entity ordering operations within of the [Core +API]{.HTML-Keyboard}, which allows clients to order Entities within a payload +according to a specified collation, either ascending or descending. + +### 7.6.2 Entity ordering language + +#### 7.6.2.1 Introduction + +When a Context Consumer queries for Entities retrieved from a single context +broker, it shall be possible to request that the array of Entities returned are +ordered according to the values held within an Entity Attribute. Context Broker +implementations shall interpret such requests and return the array of Entities +sorted accordingly. + +For each Attribute name listed, one of four types of sort order can be +specified: + +- Sort in ascending order by **target value** or **target object** +- Sort in descending order by **target value** or **target object** +- Sort by distance in ascending order from a specified GeoJSON geometry +- Sort by distance in descending order from a specified GeoJSON geometry + +When sorting by ascending or descending order, the preferred sort order for +numbers and datetimes is trivial, however for strings the default collation +order shall be defined as using ICU "root" collation order +(["und-x-icu"]{.HTML-Code}) which returns a reasonable language-agnostic sort +order (see IETF RFC 6067 [n.15]). + +Sort by distance shall be limited to GeoProperties, and shall be defined as +calculating spherical distance using the Haversine formula. + +Sort ordering is **never applied** to distributed operations, and the defined +sort ordering strategy may depend on implementation specific configurations. + +#### 7.6.2.2 Datatype comparison order + +When sorting by value, and the values of Attributes are of mixed datatypes, the +following comparison order (_`null`_ values last), shall be implicitly applied: + +- Numbers +- Strings +- Object +- Array +- Boolean +- _Time_ +- _Date_ +- _DateTime_ +- Null +- Attribute does not exist + +Additionally, when sorting by distance, the following comparison order, shall be +applied: + +- Attribute is a _GeoProperty_ +- Attribute is not a _GeoProperty_ - sorted by value as shown above. + +#### 7.6.2.3 NGSI-LD Entity ordering language + +The NGSI-LD Entity Ordering Language shall be supported by implementations for +the order parameter (i.e. _`orderBy`_). Its aim is to specify the Attributes to +be used when ordering an Array of Entities retrieved. Ordering Attributes are +specified as a disjunction of elements, where each element can either directly +be an Attribute name, or an Attribute name followed by a direction (either +ascending or descending, where ascending shall be the default if not supplied). +The comma character shall be used to separate the elements to be used for +ordering which shall be applied sequentially. + +In the following, ABNF grammar for NGSI-LD Entity Ordering Language is given. + + + +```text +thenOp = %x2C ; , +directionOp ::= asc | desc | dist-asc| +dist-desc +OrderingTerm = AttrName *1(DirectionTerm) *(thenOp OrderingTerm) +DirectionTerm = %x3B directionOp. ; ; +``` + + + +See clause 7.2.3 for the definition of [AttrName]{.HTML-Sample}. + + + +>>> [!tip] EXAMPLE 1: + +[?orderBy=name]{.HTML-Code} - applies sort ordering to rank Entities in ascending order using the value of the _`name`_ Attribute. + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +[?orderBy=name,age]{.HTML-Code} - applies sort ordering to rank Entities in ascending order using the value of the _`name`_ Attribute and thereafter where multiple Entities have the same _`name`_ , by ascending order using the _`age`_ Attribute. + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +[?orderBy=name,age;desc ]{.HTML-Code} - applies sort ordering to rank Entities in ascending order using the value of the _`name`_ Attribute and thereafter where multiple Entities have the same _`name`_ , by descending order using the value of _`age`_ Attribute. + +>>> + + + + + +>>> [!tip] EXAMPLE 4: + +[?orderBy=address[​city]]{.HTML-Code} - applies sort ordering using a sub-item within a Property Value defined as a complex JSON object. The trailing path is [[​city]]{.HTML-Code}. It is used to refer to a particular subitem within the value of the _`address`_ [Property]{.HTML-Definition}. + +>>> + + + + + +>>> [!tip] EXAMPLE 5: + +[?orderBy=name.observedAt ]{.HTML-Code} - applies sort ordering based on an attribute path that is defined by the production rule Attribute , as a dot-separated list of names. Such a list is intended to address a [Property]{.HTML-Definition} or [Relationship]{.HTML-Definition} included by the matching entities subjacent graph. + +>>> + + + +When sorting data using a specific ICU collation order as defined by IETF RFC +6067 [n.15], the collation element (parameter name **collation**) shall +represent the preferred ordering. + + +>>> [!tip] EXAMPLE 6: + +[?orderBy=name&collation=und-u-ks-identic ]{.HTML-Code} - applies sort ordering to rank Entities in ascending order using the case insensitive value of the _`name`_ Attribute. + +>>> + + + + + +>>> [!tip] EXAMPLE 7: + +[?orderBy=name&collation=de-u-co-phonebk ]{.HTML-Code} - applies sort ordering to rank Entities in ascending order using the value of the _`name`_ Attribute and sorted according to German phonebook collation ordering. + +>>> + + + +For sort by distance, the coordinates element (parameter name **orderFrom**) +shall represent the coordinates of the reference geometry as mandated by IETF +RFC 7946 [n.4], section 3.1.2. + + + +>>> [!tip] EXAMPLE 8: + +[?orderBy=location;dist-asc&orderFrom=[​8,40]]{.HTML-Code} - applies sort ordering to rank Entities in ascending distance from a Point with respect to the _`location`_ [GeoProperty]{.HTML-Definition}. + +>>> + + + + + +>>> [!tip] EXAMPLE 9: + +[?orderBy=location;dist-desc&orderFrom=[​8,40]]{.HTML-Code} - applies sort ordering to rank Entities in descending distance from a Point with respect to the _`location`_ [GeoProperty]{.HTML-Definition}. + +>>> + + + + + +>>> [!tip] EXAMPLE 10: + +``` text +?orderBy=location;dist-asc +&orderFrom=[[8,40],[9,42],[9,45],[8,40]] +&orderGeometry=LineString +``` + +>>> + + + +## 7.7 Linked Entity retrieval + +### 7.7.1 Introduction + +Since Entities are uniquely identifiable by a URI, it is possible to traverse +across the Entity graph directly from a [Linking Entity]{.HTML-Keyboard} to a +[Linked Entity]{.HTML-Keyboard}. It is therefore sometimes convenient to be able +to query or retrieve data via a single [Context Broker]{.HTML-Keyboard} request +and to receive a response including both [Linking Entities]{.HTML-Keyboard} and +dependent [Linked Entities]{.HTML-Keyboard} directly. + +The concept of Entity graph retrieval is a common concept amongst graph +databases and it allows for more structured queries (see clause 7.2.3) and the +complete serialization of an Entity and its dependents. + +When retrieving [Linked Entities]{.HTML-Keyboard}, it is necessary to limit +retrieval to avoid cascades of an excessive length, duplicates or loops. Only +_Relationships_ targeting a locally stored Entity or _Relationships_ annotated +with an _`objectType`_ whose _`object`_ is an **Internal** [Linked +Entity]{.HTML-Keyboard} are considered to be retrievable in this manner. + +### 7.7.2 Inline Linked Entity representation + +With the inline representation, the [Context Broker]{.HTML-Keyboard} response +shall only consist of [Linking Entities]{.HTML-Keyboard} - either a single +[Linking Entity]{.HTML-Keyboard}, or an array consisting of [Linking +Entities]{.HTML-Keyboard}. The additional Entity data from [Linked +Entities]{.HTML-Keyboard} is returned via a Sub-Attribute added to annotated +_Relationships_. This inline representation is generated for output only. + +An example of this representation can be found in annex C, clause C.2.2.1.2 + +### 7.7.3 Flattened Linked Entity representation + +With the flattened representation, the [Context Broker]{.HTML-Keyboard} response +shall always consist of an array of Entities. This array will consist of both +[Linking Entities]{.HTML-Keyboard} and [Linked Entities]{.HTML-Keyboard} (where +the retrieved [Linked Entities]{.HTML-Keyboard} defined by an annotated +[Relationship]{.HTML-Definition}), are appended to the array. This flattened +representation allows for batch operations (see clauses 10.3.2, 10.3.3, 10.3.4 +and 10.3.6) be applied directly using the response from the [Context +Broker]{.HTML-Keyboard}. + +An example of this representation can be found in annex C, clause C.2.2.1.3. + +## 7.8 Tenants + +#### 7.8.1 Introduction + +The concept of a [Tenant]{.HTML-Keyboard} is that a user or group of users +utilizes a single instance of an NGSI-LD system ([Context +Source]{.HTML-Keyboard} or [Context Broker]{.HTML-Keyboard}) in isolation from +other users or groups of users of the same instance, which are considered to be +different [Tenants]{.HTML-Keyboard}. Thus a multi-tenant NGSI-LD system is a +system where a single software instance is used by different users or groups of +users, the [Tenants]{.HTML-Keyboard}, where any information related to one +[Tenant]{.HTML-Keyboard} (e.g. Entities, Subscriptions, [Context Source +Registrations]{.HTML-Keyboard}) are only visible to users of the same +[Tenant]{.HTML-Keyboard}, but not to users of a different +[Tenant]{.HTML-Keyboard}. Typically, multi-tenancy is used together with an +access control mechanism, enforcing the isolation of [Tenants]{.HTML-Keyboard}, +however access control and other security-related aspects are out-of-scope of +the present document. + +The NGSI-LD API optionally enables multi-tenant systems. To support this, +[Tenant]{.HTML-Keyboard} information can be optionally specified in NGSI-LD API +operations. The operation then only applies to the targeted +[Tenant]{.HTML-Keyboard}. As all information of one [Tenant]{.HTML-Keyboard} is +isolated from other [Tenants]{.HTML-Keyboard}, the NGSI-LD API operations for +managing, retrieving and subscribing to entity information, but also any context +source related operations only apply to the information of the specified +[Tenant]{.HTML-Keyboard} in isolation and never have any effect on the +information of other [Tenants]{.HTML-Keyboard}. + +As the support and use of [Tenants]{.HTML-Keyboard} is optional, any operation +not explicitly specifying a [Tenant]{.HTML-Keyboard} targets a default +[Tenant]{.HTML-Keyboard}, which always exists. NGSI-LD systems not supporting +multiple [Tenants]{.HTML-Keyboard} should raise an error of type +[NoMultiTenantSupport]{.HTML-Error} if a [Tenant]{.HTML-Keyboard} is specified. +To enable [Context Sources]{.HTML-Keyboard} to be part of tenant-based +distributed or federated systems, [Tenant]{.HTML-Keyboard} information can +optionally be specified in [Context Source Registrations]{.HTML-Keyboard}. When +contacting the respective [Context Sources]{.HTML-Keyboard}, the +[Tenant]{.HTML-Keyboard} information from the [Context Source +Registration]{.HTML-Keyboard} has to be used. If no [Tenant]{.HTML-Keyboard} +information is present in the [Context Source Registration]{.HTML-Keyboard}, no +[Tenant]{.HTML-Keyboard} information is to be used and thus the default +[Tenant]{.HTML-Keyboard} is targeted on the registered [Context +Source]{.HTML-Keyboard}. This enables integrating [Context +Sources]{.HTML-Keyboard} not supporting multi-tenancy in a distributed system +with a [Tenant]{.HTML-Keyboard}-based [Context Broker]{.HTML-Keyboard} or +integrating local [Tenants]{.HTML-Keyboard} in a federated system using a +different [Tenant]{.HTML-Keyboard}. + +#### 7.8.2 Multi-Tenant Behaviour + +If a [Tenant]{.HTML-Keyboard} is specified for an NGSI-LD operation, the +operation shall only be applied to information related to the specified +[Tenant]{.HTML-Keyboard}. If no [Tenant]{.HTML-Keyboard} is specified, the +operation shall apply to the implicitly existing default +[Tenant]{.HTML-Keyboard}. If a [Tenant]{.HTML-Keyboard} is explicitly specified, +but the system implementing the NGSI-LD API does not support multi-tenancy, an +error of type [NoMultiTenantSupport]{.HTML-Error} should be raised. + +In case an operation applies to a [Tenant]{.HTML-Keyboard}, this information +shall also be provided in the response to the operation. This also applies to +notifications sent as a result of subscriptions (clauses 10.5 and 12.4). + +A [Tenant]{.HTML-Keyboard} is represented in form of a String. How the +[Tenant]{.HTML-Keyboard} is specified for an API operation is protocol binding +specific. How [Tenants]{.HTML-Keyboard} are created, is implementation-specific. + +One implementation option is to support the implicit creation of +[Tenants]{.HTML-Keyboard}. This means that a [Tenant]{.HTML-Keyboard} is +implicitly created when an NGSI-LD operation for creating information targets a +new [Tenant]{.HTML-Keyboard}; this is the case for: + +- Create Entity (clause 10.2.2). +- Batch Entity Creation (clause 10.3.2). +- Create or Update Temporal Evolution of an Entity (clause 11.2.2). +- Create Subscription (clause 10.5.2). +- Register Context Source (clause 12.2.2). +- Create Context Source Registration (clause 12.4.2). + +All other NGSI-LD operations, e.g. for retrieving, updating, appending or +deleting information that target a non-existing [Tenant]{.HTML-Keyboard} should +raise an error of type [NonexistentTenant]{.HTML-Error}. + +If the system implementing the NGSI-LD API does not support multiple +[Tenants]{.HTML-Keyboard}, the attempt to register a [Context +Source]{.HTML-Keyboard} with [Tenant]{.HTML-Keyboard} information in the +[Context Source Registration]{.HTML-Keyboard} should also result in an error of +type [NoMultiTenantSupport]{.HTML-Error} + +## 7.9 Snapshots + +#### 7.9.1 Introduction + +Context information can be dynamic, e.g. when a query result contains many +Entities, and the user has to paginate through the result set, the values +encountered later may be from a much later point in time than earlier results, +making them incomparable. To get more consistent results, the Snapshot concept +is introduced, which can be optionally implemented by Context Brokers. It +enables "freezing" the result by retrieving all results immediately and +persisting them locally. [Context Consumers]{.HTML-Keyboard} can then query and +analyse the Snapshot in a much more consistent way. + +This is especially relevant for distributed cases, where information initially +was distributed across multiple [Context Brokers]{.HTML-Keyboard} and [Context +Sources]{.HTML-Keyboard}. + +Snapshots offer the full functionality of NGSI-LD available locally and can be +used as a basis for simulations that enable making predictions or "what-if" +analyses, which are often needed for digital twins. + +#### 7.9.2 Snapshot Behaviour + +If a [Snapshot]{.HTML-Keyboard} is specified for an NGSI-LD operation, the +operation shall only be applied to information related to the specific +[Snapshot]{.HTML-Keyboard}. Operations permitted on Snapshots are the same as +those specified for the Core API and, if supported, the Temporal API (see Table +4.3.5-1). This means all operations are implicitly limited to a local scope with +all relaxations allowing broader operations (see clause 8.6) and there is no +need to explicitly set the local scope as a request parameter. The implicit +limitation to local scope also means that [Context Source +Registrations]{.HTML-Keyboard} from the [Context Registry]{.HTML-Keyboard} will +not be used. + +[Snapshots]{.HTML-Keyboard} are explicitly created, and the +[Snapshot]{.HTML-Keyboard} identifier is provided on creation. How the +[Snapshot]{.HTML-Keyboard} identifier is specified for an API operation is +protocol binding specific. + +The [Snapshot]{.HTML-Keyboard} concept is orthogonal to the +[Tenant]{.HTML-Keyboard} concept (see clause 7.8). [Snapshots]{.HTML-Keyboard} +can also be created on [Tenants]{.HTML-Keyboard}. To execute an operation on a +Snapshot created on a [Tenant]{.HTML-Keyboard}, both [Snapshot]{.HTML-Keyboard} +and [Tenant]{.HTML-Keyboard} (see clause 7.8.2) have to be specified for an API +operation. + +If an implementation determines that it is low on resources, it may delete one +or more snapshots. For determining the order in which snapshots are to be +deleted, the _`snapshotPriority`_, ranging from [1]{.HTML-Code} (minimum) to +[10]{.HTML-Code} (maximum) with 5 being the default priority, should be +considered. An implementation may also consider other aspects like the +_`expiresAt`_, or _`lastUsedAt`_ timestamp for such a decision. diff --git a/md/clause-8.md b/md/clause-8.md new file mode 100644 index 0000000000000000000000000000000000000000..663a462970cac18d71b4c9950f8d583c1284f8f2 --- /dev/null +++ b/md/clause-8.md @@ -0,0 +1,727 @@ +# 8 Common API behaviours + +## 8.1 Introduction + +This clause defines common behaviours for the API operations. + +When comparing URIs, implementations shall follow the recommendations of IETF +RFC 3986 [n.18], section 6. + +## 8.2 JSON-LD processing + +### 8.2.1 Introduction + +This clause outlines the requirements and procedures for processing JSON-LD +inputs, including the handling of default contexts and validation rules. + +### 8.2.2 Default \@context assignment + +If the input provided by an API client does not include any _`@context`_, then +the implementation shall at minimum assign the Core _`@context`_ to such an +input. In addition, the [Context Broker]{.HTML-Keyboard} implementation may +allow configuring a default user _`@context`_ (with default terms), to be used +when no user _`@context`_ is provided. The Core _`@context`_ shall always take +precedence. + +### 8.2.3 General NGSI-LD validation + +All the operations that take a JSON-LD document as input shall process such +JSON-LD document as follows: + +- If the request payload body is not a valid JSON document then an error of type + [InvalidRequest]{.HTML-Error} shall be raised. +- If the data included by the JSON-LD document is not syntactically correct, + according to the _`@context`_ or the API data type definitions, then an error + of type [BadRequestData]{.HTML-Error} shall be raised. +- A [Context Producer]{.HTML-Keyboard} may supply an additional hint regarding + the overall validity of the payload body and the version of the NGSI-LD + specification that the API datatype definitions conform to. When receiving + such an annotated context production request, a [Context + Broker]{.HTML-Keyboard} that it is only partially capable of interpreting the + datatypes held within the payload body may use this information to amend the + data held within the payload through applying fallbacks (see + Clause+++clause-9+++9.5.3) prior to validation. +- Any attempt to use ["urn:ngsi-ld:null"]{.HTML-Code} as a first level member + value [("<​key>": "urn:ngsi-ld:null")]{.HTML-Code}, with the + exception of NGSI-LD Fragments (see Clause+++clause-5+++5.4) used in partial + update and merge operations (as mandated by Clause+++root.4.2 and + Clause+++root.4.3) or to represent deleted Properties in concise + representation as part of notifications, shall result in an error of type + [BadRequestData]{.HTML-Error}. +- Any attempt to use ["urn:ngsi-ld:null"]{.HTML-Code} as the right-hand side of + _`value`_ in a _Property_, as the right-hand side of _`object`_ in a + _Relationship_ or to use [{"@none": "urn:ngsi-ld:null"}]{.HTML-Code} as + the right-hand side of _`languageMap`_, with the exception of NGSI-LD + Fragments (see Clause+++clause-5+++5.4) used in update and merge operations + (as mandated by Clause+++root.4.2 and Clause+++root.4.3) and the + representation of deleted Properties, Relationships or Language Properties in + notifications and the temporal evolution, shall result in an error of type + [BadRequestData]{.HTML-Error}. +- Any attempt to use ["urn:ngsi-ld:null"]{.HTML-Code} as the value of a key + value pair within a JSON object, which is the right-hand side of the _`value`_ + of a _Property_, with the exception of NGSI-LD Fragments used in merge + operations (see Clause+++root.4.3), shall result in an error of type + [BadRequestData]{.HTML-Error}. + +### 8.2.4 Term to URI expansion or compaction + +NGSI-LD API operations allow clients to use short-hand strings as non-qualified +names, particularly for _Property_, _Relationship_ or Type names and +[VocabProperty]{.HTML-Keyboard} values. For instance, an API client can refer to +the term ["Vehicle"]{.HTML-Code} as a non-qualified type name. When executing +API update-related operations, NGSI-LD systems shall expand terms to URIs, in +order to obtain and store Fully Qualified Names. Likewise, when executing +query-related operations, NGSI-LD systems shall compact URIs (Fully Qualified +Names) to short terms in order to provide short-hand strings to context +consumers. + +The term to URI expansion or compaction shall be performed using a _`@context`_ +as described by the JSON-LD specification [n.8], section 5.1, and in +Clause+++clause-5+++5.3.2.1. **In the absence of a user _`@context`_, the term +expansion or compaction shall be performed according to Clause+++root.2.2**. + +For the avoidance of doubt, the _`@context`_ used to perform compaction or +expansion of terms **shall be the one provided by each API call** (or the +default _`@context`_ in its absence), and not any other _`@context`_ which might +have been supplied previously. For instance, when performing "Query Entities" +operations (Clause+++clause-10+++10.4.3), the _`@context`_ used to perform URI +expansion and compaction shall be the one provided by the request. + +In case of HTTP binding via GET (see [i.16] ~clause 7.2.3.1) of the "Query +Entities" operation, this means using the JSON-LD Link Header as described by +the JSON-LD specification [n.8], section 6.2. In case of HTTP binding via POST +(see [i.16] ~clause 7.12.3.1), of the "Query Entities" operation, this means +giving the _`@context`_ either via Link Header or within the payload body, +depending on the Content-Type Header being ["application/json"]{.HTML-Code} or +["application/ld+json"]{.HTML-Code}, respectively. + +It is important to warn users that updating a _`@context`_ could lead to +behaviour that might be perceived as inconsistent. If, for instance, a fully +qualified name that qualified a given short-hand name is changed, from that +moment onwards, the short-hand name is referencing a different Attribute. This +will effectively change the results of queries that use the given short name, +possibly not giving back anymore the expected set of results. + +Moreover, this user _`@context`_ shall not: + +- Contain JSON-LD Scoped Contexts (see [n.8], section 4.1.8). +- Be embedded into NGSI-LD Attributes, i.e. there cannot be parts of the user + _`@context`_ other than at the top level of the NGSI-LD document. + +Parts of user _`@context`_ that are not following the two points above should +result in an error of type [BadRequestData]{.HTML-Error}, because JSON-LD Scoped +Contexts and nested embedded _`@context`_ could be used to modify terms defined +in the Core _`@context`_ or to reshape NGSI-LD Elements during the expansion of +terms. + +As the Core _`@context`_ is protected and cannot be overridden, when performing +term to URI expansion or compaction, implementations **shall always consider the +Core _`@context`_ as having absolute precedence**, regardless of the position of +the Core _`@context`_ in the _`@context`_ array of elements. Nonetheless, +NGSI-LD data providers may use appropriate term prefixing to ensure that a +proper term to URI expansion or compaction is performed. + +At compaction time, in the event that no matching term is found in the current +_`@context`_, implementations shall render Fully Qualified Names. + + + +>>> [!tip] EXAMPLE 1: + +An entity of type ["Vehicle"]{.HTML-Code} bound to a certain _`@context`_ , C, will match a query by ["Vehicle" ]{.HTML-Code} type if and only if the supplied query _`@context`_, Q, maps the term ["Vehicle"]{.HTML-Code} to the same URI as C. + +>>> + + + +Note that the _JsonProperty_ is designed to hold native JSON values which are by +definition not available for expansion and compaction via an _`@context`_. +Therefore, the given short-hand name is always used for accessing JSON keys +within a _JsonProperty_ _`json`_ element. + +### 8.2.5 Implicit creation of \@context + +## 8.3 Errors and error handling + +### 8.3.1 Introduction + +This clause defines the error types, common error handling procedures and +response formats for NGSI-LD API operations. + +### 8.3.2 Error types + +Table+++below details a list of error types defined by NGSI-LD. The particular +conditions under which error type shall be raised are defined when describing +each operation supported by the API. + + + +::: TH +Table: Error types in NGSI-LD +::: + +::: TAL ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| Error Type | Description | ++===========================================================+=====================================================================================================================================================+ +| https://uri.etsi.org/ngsi-ld/errors/AlreadyExists | The referred element already exists. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/BadRequestData | The request includes input data which does not meet the requirements of the operation. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/Conflict | The operation conflicts with the current state of the system. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/InternalError | There has been an error during the operation execution. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/InvalidRequest | The request associated to the operation is syntactically invalid or includes wrong content. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable | A remote JSON-LD \@context referenced in a request cannot be retrieved by the NGSI-LD Broker and expansion or compaction cannot be performed. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport | The NGSI-LD API implementation does not support multiple tenants. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant | The addressed tenant does not exist. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported | The operation is not supported. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound | The referred resource has not been found. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery | The query associated to the operation is too complex and cannot be resolved. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +| https://uri.etsi.org/ngsi-ld/errors/TooManyResults | The query associated to the operation is producing so many results that can exhaust client or server resources. It should be made more restrictive. | ++-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +### 8.3.3 Error response payload body + +When reporting errors back to clients, NGSI-LD implementations shall generate a +JSON object in accordance with IETF RFC 7807 [n.6], section 3.1, including, at +least the following terms: + +- **type:** Error type as per Clause+++root.3.2. +- **title:** Error title which shall be a short string summarizing the error. +- **detail:** A detailed message that should convey enough information about the + error. + +Even though IETF RFC 7807 [n.6] defines a specific MIME type for error payloads, +NGSI-LD implementations shall use the standard JSON MIME type +(["application/json"]{.HTML-Code}) when reporting errors, so that old clients or +existing tools are not broken. + + + +>>> [!tip] EXAMPLE 1: + +```json +{ + "type": "https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound", + "title": "Resource not found.", + "detail": "urn:ngsi-ld:Device:widget001 was not found", + "status": 404, + "instance": "urn:ngsi-ld:Device:widget001" +} +``` + +>>> + + + +### 8.3.4 Operation execution and generic error handling + +When executing an operation if an unexpected error happens and the operation +cannot be completed, implementations shall raise an error of type +[InternalError]{.HTML-Error}. This includes, as well, situations such as +database timeouts, etc. + +If the NGSI-LD endpoint is not capable of executing the requested operation, an +error of type [OperationNotSupported]{.HTML-Error} shall be raised. This may +happen in a distributed architecture where a [Context Broker]{.HTML-Keyboard} +might not be able to store Entities (only to forward queries to [Context +Sources]{.HTML-Keyboard}), and as a result, certain operations such as "Create +Entity" might not be supported. + +When a query operation is so complex that it cannot be resolved by an NGSI-LD +system, implementations shall raise an error of type +[TooComplexQuery]{.HTML-Error}. + +When a query operation is producing so many results that can potentially exhaust +client or server resources, or it can be just impractical to be managed, +implementations shall raise an error of type [TooManyResults]{.HTML-Error}. The +threshold conditions used as criteria to raise such error is up to each +implementation. + +When a remote JSON-LD _`@context`_ referenced by an incoming request is not +available, implementations shall raise an error of type +[LdContextNotAvailable]{.HTML-Error}. If the remote JSON-LD _`@context`_ is +invalid, implementations shall raise an error of type +[BadRequestData]{.HTML-Error}. + +## 8.4 Common operation behaviours + +### 8.4.1 Introduction + +Attribute data within NGSI-LD elements can be altered using three separate +mechanisms: + +- Partial update patch operations of Attributes at the Attribute level +- Partial update patch operations of Attributes at the Entity level +- Merge patch operations of Attributes at the Entity level + +The Partial update operation maintains the integrity of the Attribute through +ensuring that all data held within a NGSI-LD Fragment at specified level is +replaced, whereas Merge patch operations can be used to replace both individual +attributes and sub-attributes simultaneously. + +Both Partial update patch and Merge patch operations support the removal of data +through setting the value within a NGSI-LD Fragment to +["urn:ngsi-ld:null"]{.HTML-Code} + +### 8.4.2 Partial update patch behaviour + +The Partial Update Patch procedure modifies an existing NGSI-LD element by +overwriting the data at the Attribute level, replacing it with the data provided +in the NGSI-LD Fragment. + +When updating NGSI-LD elements (Entities, [Context Source +Registrations]{.HTML-Keyboard} or Context Subscriptions) using NGSI-LD +Fragments, implementations shall determine the exact set of changes being +requested by comparing the content of the provided Fragment (patch) against the +current content (a JSON-LD object) of the target element. + +With respect to update operations, implementations shall perform an algorithm +equivalent to the one described below (adapted from IETF RFC 7396 [n.17]), in +order to observe the name to URI expansion rules and the JSON-LD _`null`_ +processing: + +- For each member of the Fragment perform the term to URI expansion. +- For Entity fragments, apply the **concise to normalised** expansion as defined + in Clause+++clause-5+++5.3.2.3 if necessary. +- If the provided Fragment (a JSON Merge Patch document) contains members that + do not appear within the target (their URIs do not match), those members are + added to the target. +- For each member of the Fragment contained by the target, the target member + value is replaced by the value given in the Fragment. In the case of a member + representing a reified _Property_ or _Relationship_ including a _`datasetId`_, + such member is only replaced if the _`datasetId`_ is the same, otherwise the + member of the Fragment is added as a new instance to the target. If no + _`datasetId`_ is present, the default Attribute instance is targeted and + replaced if present and otherwise added. In case of a member _`type`_ (of an + entity) in Entity Fragments, all included Entity Types are added, if they are + not already contained in the _`type`_ member of the target. +- For each member of the Fragment, whose value is an NGSI-LD Null, contained by + the target, the target member is deleted. In the case of deleting a specific + Attribute instance with a _`datasetId`_, the handling shall be in accordance + with the description found in Clause+++clause-10+++10.2.7. A _`datasetId`_ + cannot be deleted by setting it to the value ["urn:ngsi-ld:null".]{.HTML-Code} + +**Partial Update at the Attribute Level** + +Applying **partial attribute update** operation (as defined in +Clause+++clause-10+++10.2.5), results in the replacement of the key-value pairs +defined in payload of the Attribute Fragment. + + + +>>> [!tip] EXAMPLE 1: + +Given an Entity containing the following _Property_: + +```json +{ + "temperature": { + "type": "Property", + "value": 25, + "unitCode": "CEL", + "observedAt": "2022-03-14T01:59:26.535Z" + } +} +``` + +Applying **partial attribute update** operation at the Attribute level onto the +[temperature]{.HTML-Code} Attribute, with the following Attribute Fragment +payload: + +```json +{ + "type": "Property", + "value": 100, + "observedAt": "2022-03-14T13:00:00.000Z" +} +``` + +Results in an overwrite of the [value]{.HTML-Code} and [observedAt]{.HTML-Code} +sub-Attributes, leaving the [unitCode]{.HTML-Code} sub-Attribute untouched as +shown: + +```json +{ + "temperature": { + "type": "Property", + "value": 100, + "unitCode": "CEL", + "observedAt": "2022-03-14T13:00:00.000Z" + } +} +``` + +>>> + + + +**Partial Update of Attributes at the Entity Level** + +Applying an **update attributes** operation (as defined in +Clause+++clause-10+++10.2.3), results in the overwrite of the whole Attribute +with the key-value pairs defined in payload of the Attribute Fragment. + + + +>>> [!tip] EXAMPLE 2: + +Given an Entity containing the following _Property_: + +```json +{ + "temperature": { + "type": "Property", + "value": 25, + "unitCode": "CEL", + "observedAt": "2022-03-14T01:59:26.535Z" + } +} +``` + +Applying an **update attributes** operation onto the Entity as a whole with the following +Entity Fragment payload: + +```json +{ + "temperature": { + "type": "Property", + "value": 100, + "observedAt": "2022-03-14T13:00:00.000Z" + } +} +``` + +Results in an overwrite of the whole [temperature]{.HTML-Code} Attribute - other +Attributes would remain untouched. The result is that the [value]{.HTML-Code} +and [observedAt]{.HTML-Code} sub-Attributes are updated and the +[unitCode]{.HTML-Code} sub-Attribute is removed as shown: + +```json +{ + "temperature": { + "type": "Property", + "value": 100, + "observedAt": "2022-03-14T13:00:00.000Z" + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 3: + +Given an Entity containing the following _Property_: + +```json +{ + "temperature": { + "type": "Property", + "value": 25, + "unitCode": "CEL", + "observedAt": "2022-03-14T01:59:26.535Z" + } +} +``` + +Applying an **update attributes** operation onto the Entity as a whole, with the following +Entity Fragment payload: + +```json +{ + "temperature": { + "type": "Property", + "value": "urn:ngsi-ld:null" + } +} +``` + +Results in the deletion of the whole [temperature]{.HTML-Code} Attribute - all +other Attributes remain untouched. + +>>> + + + +### 8.4.3 Merge patch behaviour + +The merge patch procedure modifies an existing NGSI-LD element by applying the +set of changes found in an NGSI-LD Fragment data to the target resource. Unlike +the partial update patch behaviour (described in Clause+++root.4.2), which +replaces the complete element on the first level, e.g. a whole Attribute, the +procedure described in this clause merges the provided information with the +existing information up to an arbitrary depth, e.g. including going into JSON +objects representing a Property value. + +When merging NGSI-LD Entities using NGSI-LD Fragments, implementations shall +determine the exact set of changes being requested by comparing the content of +the provided Fragment (patch) against the current content (a JSON-LD object) of +the target element. + +With respect to merge operations, implementations shall perform an algorithm +equivalent to the one described below (adapted from IETF RFC 7396 [n.17], in +order to observe the name to URI expansion rules and JSON-LD _`null`_ +processing): + +- For each member of the Fragment perform the term to URI expansion +- For Entity fragments, apply the **concise to normalised** expansion as defined + in Clause+++clause-5+++5.3.2.3 if necessary. +- If the provided Fragment (a JSON Merge Patch document) contains members that + do not appear within the target (their URIs do not match), those members are + added to the target. +- For each member of the Fragment contained by the target, the target member + value is **merged** with the value given in the Fragment. NGSI-LD Nulls within + the Fragment are given special meaning to indicate the removal of existing + values within the target member value. In the case of a member representing a + reified _Property_ or _Relationship_ including a _`datasetId`_, such member is + only updated if the _`datasetId`_ is the same, otherwise the member of the + Fragment is added as a new instance to the target. If no _`datasetId`_ is + present, the default Attribute instance is targeted and merged if present and + otherwise added. In case of a member _`type`_ (of an Entity) in Entity + Fragments, all included Entity Types are added, if they are not already + contained in the _`type`_ member of the target. +- For each member of the Fragment, whose value is an NGSI-LD Null, contained by + the target, the target member is removed. In the case of deleting a specific + Attribute instance with a _`datasetId`_, the handling shall be according to + the description in Clause+++clause-10+++10.2.7. A _`datasetId`_ cannot be + deleted by setting it to the value ["urn:ngsi-ld:null"]{.HTML-Code}. + + + +>>> [!tip] EXAMPLE 1: + +Given an Entity containing the following _Property_: + +```json +{ + "temperature": { + "type": "Property", + "value": 25, + "unitCode": "CEL", + "observedAt": "2022-03-14T01:59:26.535Z" + } +} +``` + +Applying a **merge entity** operation (as defined in +Clause+++clause-10+++10.2.9) onto the Entity as a whole, with the following +Entity Fragment payload: + +```json +{ + "temperature": { + "type": "Property", + "value": 100, + "observedAt": "2022-03-14T13:00:00.000Z" + } +} +``` + +Results in the update of the _`value`_ and _`observedAt`_ sub-Attributes and +leaves the _`unitCode`_ sub-Attribute untouched, as shown: + +```json +{ + "temperature": { + "type": "Property", + "value": 100, + "unitCode": "CEL", + "observedAt": "2022-03-14T13:00:00.000Z" + } +} +``` + +>>> + + + + + +>>> [!tip] EXAMPLE 2: + +Given an Entity containing the following _Property_: + +```json +{ + "address": { + "type": "Property", + "value": { + "street": "Straße des 17. Juni", + "city": "Berlin", + "country": "Germany" + } + } +} +``` + +Applying a **merge entity** operation (as defined in +Clause+++clause-10+++10.2.9) onto the Entity as a whole with the following +Entity Fragment payload: + +```json +{ + "address": { + "type": "Property", + "value": { + "street": "Pariser Platz", + "country": "urn:ngsi-ld:null" + } + } +} +``` + +Results in the updating of the _`address`_ Attribute value applying the JSON +Merge Patch processing rules as defined in IETF RFC 7396 [n.17], updating +_`street`_ and removing _`country`_ resulting as shown: + +```json +{ + "address": { + "type": "Property", + "value": { + "street": "Pariser Platz", + "city": "Berlin" + } + } +} +``` + +>>> + + + +## 8.5 Multi-Attribute behaviour + +### 8.5.1 Introduction + +For each Entity, there can be Attributes that simultaneously have more than one +instance. In the case of Properties, there may be more than one source at a time +that provides a Property instance, e.g. based on independent sensor measurements +with different quality characteristics. For instance, take a speedometer and a +GPS both providing the current speed of a car. In the case of Relationships, +there may be non-functional Relationships requiring separate metadata attached +to each object, e.g. for a room, there may be multiple ["contains"]{.HTML-Code} +Relationships to all sorts of objects currently in the room that have been put +there by different people (a separate ["placedBy"]{.HTML-Code} +Relationship-of-the-Relationship) and which are dynamically changing over time. + +To be able to explicitly manage such multi-attributes, the optional +_`datasetId`_ property is used, which is of datatype URI, or equal to the +JSON-LD keyword ["@none"]{.HTML-Code}. It is introduced for Properties and +Relationships in Clause+++clause-5+++5.3.2.2 and Clause+++clause-5+++5.3.2.3 +respectively. If a _`datasetId`_ is provided when creating, updating, appending +or deleting Attributes, only instances with the same _`datasetId`_ are affected, +leaving instances with another _`datasetId`_ or an instance without a +_`datasetId`_ untouched. If no _`datasetId`_ is provided, or ["datasetId": +"@none"]{.HTML-Code} is supplied, it is considered as the default Attribute +instance. Thus, the creation, updating, appending or deleting of Attributes +without providing a _`datasetId`_ only affects the default Attribute instance. +There can only be one default Attribute instance for an Attribute with a given +Attribute name in any request or response. An example can be found in Annex C, +Clause+++annex-c+++C.2.2. + +When requesting Entity information, if there are multiple instances of matching +Attributes these are returned as arrays of Attributes, instead of a single +Attribute element. The _`datasetId`_ of the default Attribute instance is never +explicitly included in responses, i.e. a default Attribute instance does not +have a _`datasetId`_. + +The _`datasetId`_ can be used to create different "views" of Entities. All +Attribute instances sharing the same _`datasetId`_ can be seen as one "view". If +one or more _`datasetIds`_ are specified in the request, only the Attribute +instances that match one of the _`datasetIds`_ will be returned. The +_`datasetId`_ of the default Attribute instance can be specified as +["@none"]{.HTML-Code} In case that no Attribute instances match the provided +_`datasetIds`_, then the Attribute shall not be returned with the Entity. If no +_`datasetId`_ is provided, then all available Attribute instances will be +returned. + +There is no multi-attribute support for non-reified Attributes, in particular +this applies to the Temporal Properties _`createdAt`_, _`modifiedAt`_, +_`deletedAt`_, _`expiresAt`_ and _`observedAt`_, and also the _`unitCode`_ +Property. + +### 8.5.2 Processing of conflicting transient Entities + +In case of conflicting information when an Entity is received from a registered +[Context Source]{.HTML-Keyboard} and marked with an _`expiresAt`_ _DateTime_, +but this _`expiresAt`_ is not duplicated across all versions of the Entity +received across all registered [Context Sources]{.HTML-Keyboard}, the following +mechanism shall be used to differentiate. + +For each version of the Entity received where the _`expiresAt`_ non-reified +attribute is present at the Entity level: + +- If no _`expiresAt`_ attribute is present as a property of an Attribute, a + non-reified _`expiresAt`_ attribute is added as a property of that Attribute + corresponding to the _`expiresAt`_ found on the Entity. +- If the _`expiresAt`_ attribute is present as a property of an Attribute, and + the value on the Attribute is further in the future than the _`expiresAt`_ + value found on the Entity, the value of the _`expiresAt`_ on the Attribute is + overwritten to corresponding to the earlier _DateTime_. + +### 8.5.3 Processing of conflicting Attributes + +In case of conflicting information for an Attribute, where a _`datasetId`_ is +duplicated, but there are differences in the other attribute data, if an +_`expiresAt`_ _DateTime_ is present on the Attribute and the date lies in the +past, it shall be discarded, thereafter the one with the most recent +_`observedAt`_ _DateTime_, if present, and otherwise the one with the most +recent _`modifiedAt`_ _DateTime_ shall be provided. If no other mechanism for +determining the most current Attribute instance is found, the NGSI-LD system +shall choose the Attribute instance at random and the result is indeterminate. + +When conflicting information is received for the non-reified _`expiresAt`_ +attribute at an Entity level: + +- If an _`expiresAt`_ attribute is missing from at least one version of the + Entity received from registered [Context Sources]{.HTML-Keyboard}, the + _`expiresAt`_ attribute is removed from the Entity. +- Otherwise, the _`expiresAt`_ attribute of the Entity is set to the _DateTime_ + corresponding to the _`expiresAt`_ _DateTime_ which is furthest in the future. + +## 8.6 Limiting operations to local scope + +The API provides a binding-specific mechanism to limit the execution of +operations to a local scope, i.e. to only execute it based on information +available in the [Context Source]{.HTML-Keyboard} or [Context +Broker]{.HTML-Keyboard} directly targeted by the request. This enables limiting +cascading distributed operations (Clause+++clause-9+++9.7) and, in some cases, +also enables broader local operations, e.g. pertaining to **all** entities, +which would be too expensive in the distributed case. + +The [localOnly]{.HTML-Code} member in the Subscription +(Clause+++clause-5+++5.2.6.5.2) requests that the subscription only matches +Entities stored locally. + +The [localOnly]{.HTML-Code} member in the RegistrationManagementInfo +(Clause+++clause-5+++5.2.6.6.6) of a [Context Source +Registration]{.HTML-Keyboard} request that, when contacting the registered +[Context Source]{.HTML-Keyboard}, a local scope shall be specified. Thus, the +registered [Context Source]{.HTML-Keyboard} only provides its local information, +not information from further [Context Sources]{.HTML-Keyboard} in its own +[Context Registry]{.HTML-Keyboard}. + +If the request limits the execution of the operation to the local scope, +[Context Source Registrations]{.HTML-Keyboard} from the [Context +Registry]{.HTML-Keyboard} will not be used. + +Operations on a Snapshot (see Clause+++clause-7+++7.9) are always implicitly +local scope, overriding setting a local scope to false, i.e. such a setting is +to be ignored by implementations. diff --git a/md/clause-9.md b/md/clause-9.md new file mode 100644 index 0000000000000000000000000000000000000000..a7e2ce6c4a2bdd0f3883df5844ab56b212a8c3f1 --- /dev/null +++ b/md/clause-9.md @@ -0,0 +1,805 @@ +# 9 Distributed behaviour + +## 9.1 Introduction + +One fundamental concept underpinning all of the prototypical architectures +described above (Clause+++clause-4+++4.3.2 and Clause+++clause-4+++4.3.3) is the +idea that Entity data does not need to be centralized within a single [Context +Broker]{.HTML-Keyboard}. When reading context information, a [Context +Broker]{.HTML-Keyboard} can be used as a single point of access to retrieve +Entity data found distributed across multiple associated [Context +Brokers]{.HTML-Keyboard} each receiving a **context consumption** request. +Similarly, when modifying an Entity, a single request to a [Context +Broker]{.HTML-Keyboard} may result in the operation being distributed and +different parts of that Entity being updated across multiple [Context +Brokers]{.HTML-Keyboard} each receiving a **context provision** request. + +As long as there is only a centralized [Context Broker]{.HTML-Keyboard}, i.e. +there are no [Context Sources]{.HTML-Keyboard} registered, all NGSI-LD requests, +with few exceptions such as Update Attributes (see Clause+++clause-10+++10.2.3) +and the batch operations (see Clause+++clause-10+++10.3.2, +Clause+++clause-10+++10.3.3, Clause+++clause-10+++10.3.2, +Clause+++clause-10+++10.3.3, Clause+++clause-10+++10.3.5 and +Clause+++clause-10+++10.3.6), can either be successfully executed completely, or +result in an error. In the distributed case, all requests can be partially +successful. For the centralized case described above, only specific operations, +such as Update Attributes and the batch operations, can be partially successful. + +It is the responsibility of the [Context Broker]{.HTML-Keyboard} to respect the +registration parameters when issuing distributed requests. For instance, if a +registration states that only Entities of a given type are offered, the +distributed request does not contain additional types. Such a strict requirement +is justified because [Context Sources]{.HTML-Keyboard} (the receivers of the +distributed request) are not in a position to determine whether a request has +been triggered by a registration, rendering them unable to ensure that the +registration parameters are respected in the first place. This applies for any +kind of context data a [Context Broker]{.HTML-Keyboard} can exchange such as +Entity IDs, entity types, attribute names, geofenced areas, etc. Ultimately, all +constraints specified in the registration shall be respected. + +When a [Context Source]{.HTML-Keyboard} is registered, an operation mode is +selected. This defines the basis for distributed operations and also defines +whether or not the [Context Broker]{.HTML-Keyboard} is permitted to hold context +data about the Entities and Attributes locally itself. + +If two registered [Context Sources]{.HTML-Keyboard} are providing context data +for the same Attribute, the Attribute instances can be distinguished by +_`datasetId`_. The mechanism for determining which data shall be returned is +defined in Clause+++clause-8+++8.5. + +It is possible to restrict a registered [Context Source]{.HTML-Keyboard} to +operate on a specific Entity type or list of Entity types. In order for [Context +Broker]{.HTML-Keyboard} hierarchies to support and restrict the distribution of +such limited operations, the Entity type selector (see +Clause+++clause-7+++7.2.2) can be added as a filter on forwarded requests even +where its presence initially seems redundant. + +Furthermore, registered [Context Sources]{.HTML-Keyboard} may indicate that they +are only willing to respond to a limited subset of API operations. [Context +Brokers]{.HTML-Keyboard} shall respect this, to avoid unnecessarily sending +distributed operation requests which are always guaranteed to fail. For example, +a [Context Source]{.HTML-Keyboard} may consistently refuse certain API +operations since it does not support them. Alternatively, some [Context +Source]{.HTML-Keyboard} endpoints (such as updates) may be protected for use by +authorized users only, and not accessible to a [Context Broker]{.HTML-Keyboard} +without those rights. Limited access is likely to be the case in extended data +sharing scenarios, where a registered [Context Source]{.HTML-Keyboard}, and the +data held within it, may belong to an external third party. + +For the endpoints served, all registered [Context Sources]{.HTML-Keyboard} shall +support the normalized representation of Entities as default. Support of +additional representation formats is optional and will depend on the +implementation. System generated attributes such as _`modifiedAt`_ and +_`createdAt`_ (see Clause+++clause-5+++5.2.4) should be supported by registered +[Context Sources]{.HTML-Keyboard}, at a minimum no error shall be returned if +they are not available when requested. + +## 9.2 Distributed operation names + +When registering [Context Sources]{.HTML-Keyboard} (see +Clause+++clause-5+++5.2.6.5.3), the registrant NGSI-LD interface endpoint may +optionally offer a subset of NGSI-LD operations which it accepts. Table+++below +defines a list of names for each of these operations. + + + +::: TH +Table: Names of implemented Operations +::: + +::: TAL ++-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ +| | Operation name | Implements | ++===============================================+===============================+=============================================================================+ +| Context Information Provision | createEntity | 10.2.2 Create Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | updateEntity | 10.2.3 Update Attributes | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | appendAttrs | 10.2.4 Append Attributes | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | updateAttrs | 10.2.5 Partial Attribute update | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteAttrs | 10.2.7 Delete Attribute | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteEntity | 10.2.8 Delete Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | mergeEntity | 10.2.9 Merge Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | replaceEntity | 10.2.10 Replace Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | replaceAttrs | 10.2.11 Replace Attribute | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | purgeEntity | 10.2.12 Purge Entities | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | createBatch | 10.3.2 Batch Entity Creation | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | upsertBatch | 10.3.3 Batch Entity Creation or Update (Upsert) | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | updateBatch | 10.3.4 Batch Entity Update | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | mergeBatch | 10.3.5 Batch Entity Merge | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteBatch | 10.3.6 Batch Entity Delete | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | upsertTemporal | 11.2.2 Create or Update Temporal Evolution of an Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | appendAttrsTemporal | 11.2.3 Add Attributes to Temporal Evolution of an Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteAttrsTemporal | 11.2.4 Delete Attributes from Temporal Evolution of an Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | updateAttrInstanceTemporal | 11.2.5 Partial Update Attribute Instance in Temporal Evolution of an Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteAttrInstanceTemporal | 11.2.6 Delete Attribute Instance from Temporal Evolution of an Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteTemporal | 11.2.7 Delete Temporal Evolution of an Entity | ++-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ +| Context Information Consumption | retrieveEntity | 10.4.2 Retrieve Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | queryEntity | 10.4.3 Query Entities (excluding batch entity queries) | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | queryBatch | 10.4.3 Query Entities (batch entity queries only) | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveEntityTypes | 10.6.3 Retrieve Available Entity Types | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveEntityTypeDetails | 10.6.4 Retrieve Details of Available Entity Types | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveEntityTypeInfo | 10.6.5 Retrieve Available Entity Type Information | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveAttrTypes | 10.6.6 Retrieve Available Attributes | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveAttrTypeDetails | 10.6.7 Retrieve Details of Available Attributes | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveAttrTypeInfo | 10.6.8 Retrieve Available Attribute Information | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveTemporal | 11.3.2 Retrieve Temporal Evolution of an Entity | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | queryTemporal | 11.3.3 Query Temporal Evolution of Entities | ++-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ +| Context Information Subscription | createSubscription | 10.5.2 Create Subscription | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | updateSubscription | 10.5.3 Update Subscription | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveSubscription | 10.5.4 Retrieve Subscription | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | querySubscription | 10.5.5 Query Subscription | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteSubscription | 10.5.6 Delete Subscription | ++-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ +| Support operations for distributed operations | retrieveEntityMap | 14.2 Retrieve EntityMap | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | updateEntityMap | 14.3 Update EntityMap | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | deleteEntityMap | 14.4 Delete EntityMap | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | createEntityMapQueryEntity | 14.5 Create EntityMap for Query Entities | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | createEntityMapQueryTemporal | 14.6 Create EntityMap for Query Temporal Evolution of Entities | +| +-------------------------------+-----------------------------------------------------------------------------+ +| | retrieveContextSourceIdentity | 15.2 Retrieve Context Source Identity Information | ++-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ +::: + + + +In addition to these individual operations, a series of names for common groups +of operations have also been defined. Table+++below defines a list of names for +each of these operation groups. + + + +::: TH +Table: Named Operation Groups +::: + +::: TAL ++-------------------------------------+-------------------------------------+ +| Operation Group name | Implements | ++=====================================+=====================================+ +| federationOps | - retrieveEntity | +| | - queryEntity | +| | - queryBatch | +| | - retrieveEntityTypes | +| | - retrieveEntityTypeDetails | +| | - retrieveEntityTypeInfo | +| | - retrieveAttrTypes | +| | - retrieveAttrTypeDetails | +| | - retrieveAttrTypeInfo | +| | - createSubscription | +| | - updateSubscription | +| | - retrieveSubscription | +| | - querySubscription | +| | - deleteSubscription | +| | - retrieveEntityMap | +| | - updateEntityMap | +| | - deleteEntityMap | +| | - createEntityMapQueryEntity | +| | - retrieveContextSourceIdentity | ++-------------------------------------+-------------------------------------+ +| associationOps | - retrieveEntity | +| | - queryEntity | +| | - queryBatch | +| | - retrieveEntityTypes | +| | - retrieveEntityTypeDetails | +| | - retrieveEntityTypeInfo | +| | - retrieveAttrTypes | +| | - retrieveAttrTypeDetails | +| | - retrieveAttrTypeInfo | +| | - createSubscription | +| | - updateSubscription | +| | - retrieveSubscription | +| | - querySubscription | +| | - deleteSubscription | +| | - retrieveContextSourceIdentity | ++-------------------------------------+-------------------------------------+ +| updateOps | - updateEntity | +| | - updateAttrs | +| | - replaceEntity | +| | - replaceAttrs | ++-------------------------------------+-------------------------------------+ +| retrieveOps | - retrieveEntity | +| | - queryEntity | ++-------------------------------------+-------------------------------------+ +| redirectionOps | - createEntity | +| | - updateEntity | +| | - appendAttrs | +| | - updateAttrs | +| | - deleteAttrs | +| | - deleteEntity | +| | - mergeEntity | +| | - replaceEntity | +| | - replaceAttrs | +| | - retrieveEntity | +| | - queryEntity | +| | - purgeEntity | +| | - retrieveEntityTypes | +| | - retrieveEntityTypeDetails | +| | - retrieveEntityTypeInfo | +| | - retrieveAttrTypes | +| | - retrieveAttrTypeDetails | +| | - retrieveAttrTypeInfo | +| | - retrieveEntityMap | +| | - updateEntityMap | +| | - deleteEntityMap | +| | - createEntityMapQueryEntity | +| | - retrieveContextSourceIdentity | ++-------------------------------------+-------------------------------------+ +::: + + + +If no specific subset of operations is defined for a [Context Source +Registration]{.HTML-Keyboard}, the default set of operations matches the group +defined as ["federationOps"]{.HTML-Code}. + +## 9.3 Registrations + +### 9.3.1 Introduction + +### 9.3.2 Additive registrations + +For additive registrations, the [Context Broker]{.HTML-Keyboard} is permitted to +hold context data about the Entities and Attributes locally itself, and also +obtain data from external sources. Context provisioning operations are serviced +both locally by the [Context Broker]{.HTML-Keyboard} itself, and also +distributed on to the registered sources. + +An **inclusive** [Context Source Registration]{.HTML-Keyboard} specifies that +the [Context Broker]{.HTML-Keyboard} considers all registered [Context +Sources]{.HTML-Keyboard} as equals and will distribute operations to those +[Context Sources]{.HTML-Keyboard} even if relevant context data is available +directly within the [Context Broker]{.HTML-Keyboard} itself (in which case, all +results will be integrated in the final response). Data from every [Context +Source]{.HTML-Keyboard} registered by an inclusive [Context Source +Registration]{.HTML-Keyboard} is requested with an equal priority. This is the +default mode of operation. + +An **auxiliary** [Context Source Registration]{.HTML-Keyboard} never overrides +data held directly within a [Context Broker]{.HTML-Keyboard}. Auxiliary +distributed operations are limited to context information consumption operations +(see Clause+++clause-10+++10.4). Context data from auxiliary [Context +Sources]{.HTML-Keyboard} is only included if it is supplementary to the context +data otherwise available to the [Context Broker]{.HTML-Keyboard}. Auxiliary +[Context Source Registrations]{.HTML-Keyboard} are always accepted as there can +never be a conflict. + +### 9.3.3 Proxied registrations + +For proxied registrations, the [Context Broker]{.HTML-Keyboard} itself is not +permitted to hold context data about the registered Entities and Attributes +locally (thus all registered context data is obtained from the external +registered sources). Unregistered Attributes of an Entity are permitted to be +held locally; when context provisioning operations are received, registered +Attributes are distributed on to the registered sources and never serviced +directly by the [Context Broker]{.HTML-Keyboard} itself. + +An **exclusive** [Context Source Registration]{.HTML-Keyboard} specifies that +all of the registered context data is held in a single location external to the +[Context Broker]{.HTML-Keyboard}. The [Context Broker]{.HTML-Keyboard} itself +holds no data locally about the registered Attributes and no overlapping proxied +[Context Source Registrations]{.HTML-Keyboard} shall be supported for the same +combination of registered Attributes on the Entity. An **exclusive** +registration shall always relate to specific Attributes found on a single +Entity. Thus, the registration shall define **both:** + +- An entity id (i.e. an id pattern or Entity type defining a group of entities + is not supported for **exclusive** registrations). +- Attributes. + +Once an **exclusive** [Context Source Registration]{.HTML-Keyboard} has been +created, no further exclusive or redirect [Context Source +Registrations]{.HTML-Keyboard} can be created for that same combination of +Entity ID and Attributes. + +A **redirect** [Context Source Registration]{.HTML-Keyboard} also specifies that +the registered context data is held in a location external to the [Context +Broker]{.HTML-Keyboard}. It is possible to register (any combination of): + +- A whole Entity by id or id pattern (i.e. without specifying individual + Attributes in the registration; in this case, all Attributes are held + externally). +- Entities by Entity type only (with or without specifying individual + Attributes). +- Attributes only. + +Potentially multiple distinct **redirect** registrations can apply at the same +time. The [Context Broker]{.HTML-Keyboard} itself holds no data locally in +conflict to the registration. In the case that multiple overlapping **redirect** +registrations are defined, operations are distributed to all registered [Context +Sources]{.HTML-Keyboard}. + +## 9.4 Matching Context Source registrations + +When querying [Context Source Registrations]{.HTML-Keyboard} as described in +Clause+++clause-12+++12.3.3 and subscribing to [Context Source +Registrations]{.HTML-Keyboard} as described in Clause+++clause-12+++12.4.2, the +Entities and/or Attributes specified in the request have to be matched against +the set of [Context Source Registrations]{.HTML-Keyboard}, extracting the +matching ones. This clause describes this matching. + +The relevant specification information in the query for [Context Source +Registrations]{.HTML-Keyboard} are the selector of Entity Types (if present), +the list of Entity identifiers (if present), the id pattern (if present) and the +list of Attribute names (if present). In the case of subscriptions to [Context +Source Registrations]{.HTML-Keyboard}, it is the Entities as specified in the +array of type _EntitySelector_ in the Subscription, the _`watchedAttributes`_ +element of the Subscription and the attributes specified as part of the +_NotificationParams_ element of the Subscription. If the attributes in the +_NotificationParams_ element are empty or not present, the matching is done as +if no attribute identifiers have been specified, otherwise the combination of +the _`watchedAttributes`_ and the attributes in the _NotificationParams_ element +are used as the specified attribute identifiers for the matching. + +Even though the way relevant Entities are specified differs in queries and +subscriptions, they consist of the same information, so for the purpose of this +clause, the specification of Entity Types or Attributes refers to the relevant +elements for matching, i.e. Entity Types, Entity identifiers, id pattern and +Attribute names. A specification of Entity Types or Attributes shall contain at +least one of: + + + +a. selector of Entity Types +b. list of Attribute names. + + + +A specification of Entity Types or Attributes matches a [Context Source +Registration]{.HTML-Keyboard} if at least one of the _RegistrationInfo_ elements +(defined in Clause 5.2.6.6.4) in the _`information`_ element matches. An Entity +specification matches a _RegistrationInfo_ if the following conditions hold: + +- If present, the selector of Entity Types, Entity identifiers and id pattern + match at least one of the _EntityInfo_ elements of the _RegistrationInfo_ (see + below). +- If present, the Attribute identifiers match the combination of Properties and + Relationships specified in the _RegistrationInfo_ (see below). + +An Entity specification consisting of selector of Entity Types, Entity +identifiers and id pattern matches an _EntityInfo_ element of the +_RegistrationInfo_ if the type selector matches the entity types in the +_EntityInfo_ element (defined in clause 5.2.6.6.2) and one of the following +conditions holds: + +- The _EntityInfo_ contains neither an _`id`_ nor an _`idPattern`_. +- One of the specified Entity identifiers matches the _`id`_ in the + _EntityInfo_. +- At least one of the specified Entity identifiers matches the _`idPattern`_ in + the _EntityInfo_. +- The specified id pattern matches the _`id`_ in the _EntityInfo_. +- Both a specified id pattern and an _`idPattern`_ in the _Entity Info_ are + present (since in the general case it is not easily feasible to determine if + there can be identifiers matching both patterns). + +Attribute names match the combination of Properties and Relationships if one of +the following conditions hold: + +- No Attribute names have been specified (as this means all Attributes are + requested). +- The combination of Properties and Relationships is empty (as this means only + Entities have been registered and the [Context Sources]{.HTML-Keyboard} may + have matching Property or Relationship instances). +- If at least one of the specified attribute names matches a Property or + Relationship specified in the _RegistrationInfo_. + +If the request that triggered the matching includes a _`datasetId`_ parameter +and the CSourceRegistration to be matched contains a _`datasetId`_ element, the +CSourceRegistration should only be considered matching, if both have at least +one value in common. If only one of them specifies a _`datasetId`_, it is +considered a match. + +In the case of distributed operations (see Clause+++clause-9+++9.7), where a +listing of all previously encountered [Context Sources]{.HTML-Keyboard} is +supplied with the request, no registration shall match if the +CSourceRegistration _`contextSourceAlias`_ can be found within the listing of +previously encountered [Context Sources]{.HTML-Keyboard}. + +Note that distributed queries (see Clause+++clause-9+++9.6), can be supplied +with an _EntityMap_ (see Clause+++clause-5+++5.2.6.5.5) which lists all Entity +ids successfully matched during a previous request. If the location of an +[Entity Map]{.HTML-Keyboard} is passed into a subsequent request, the retrieved +[Entity Map]{.HTML-Keyboard} shall be used in preference to the matching +algorithm described above, provided that the [Entity Map]{.HTML-Keyboard} is +valid and has not expired. + +## 9.5 Contacting Context Sources + +### 9.5.1 Extra information to provide when contacting Context Sources + +If the optional array (of _KeyValuePair_ type, as defined by +Clause+++clause-5+++5.2.6.6.3) _`contextSourceInfo`_ of the CSourceRegistration +is present, it contains, whatever extra information the [Context +Broker]{.HTML-Keyboard} shall convey when contacting the [Context +Source]{.HTML-Keyboard}. This can be information the [Context +Broker]{.HTML-Keyboard} needs to successfully communicate with the [Context +Source]{.HTML-Keyboard} (e.g. Authorization material), or for the [Context +Source]{.HTML-Keyboard} to correctly interpret the received content (e.g. the +Link URL to fetch an _`@context`_). The method for conveying this information is +binding-specific, e.g. using headers in the case of HTTP. Instead of providing +the actual value, the special value ["urn:ngsi-ld:request"]{.HTML-Code} can be +used to indicate that the respective value is to be taken from the request that +triggered the given request, if present. + + + +>>> [!tip] EXAMPLE 1: + +If the key value pair ["user": "urn:ngsi-ld:request"]{.HTML-Code} is part of +_`contextSourceInfo`_ of the CSourceRegistration, the [Context +Broker]{.HTML-Keyboard} checks if ["user"]{.HTML-Code} was conveyed in the +triggering request. If this is the case, e.g. ["user": "abcd"]{.HTML-Code}, +["user": "abcd"]{.HTML-Code} is also conveyed when contacting the [Context +Source]{.HTML-Keyboard}. + +>>> + + + +As [Tenant]{.HTML-Keyboard} information, if applicable, is directly specified in +the CSourceRegistration, it shall not be part of _`contextSourceInfo`_. +Binding-specific information that is used for setting up the connection or is +specific for an interaction, e.g. Content-length in HTTP, cannot be overridden +by _`contextSourceInfo`_. If present, such information shall be ignored. + +### 9.5.2 Additional pre- and post-processing of extra information when contacting Context Sources + +The following key-values have a specific well-defined meaning when defined as +elements within the optional array _`contextSourceInfo`_ of the +CSourceRegistration. + +If the key ["accept"]{.HTML-Code} is defined: + +- the value shall be a MIME type acceptable to the [Context + Broker]{.HTML-Keyboard} (one of: ["application/json"]{.HTML-Code}, + ["application/ld+json"]{.HTML-Code}). +- the response from the distributed endpoint shall be returned in this defined + format and if necessary, the [Context Broker]{.HTML-Keyboard} shall be + responsible for converting this to the desired content type when aggregating + responses to the initial request. + +If the key ["contentType"]{.HTML-Code} is defined: + +- the value shall be a MIME type acceptable to the [Context + Broker]{.HTML-Keyboard} (one of: ["application/json"]{.HTML-Code}, + ["application/ld+json"]{.HTML-Code}). +- the [Context Broker]{.HTML-Keyboard} shall provide the request and the + associated _`@context`_ as required by the MIME type when distributing the + request to the context source endpoint, regardless of how it was provided in + the initial request. + +If the key ["jsonldContext"]{.HTML-Code} is defined: + +- the value shall correspond to a URL reference as defined by the JSON-LD + specification [n.8], section 3.1. +- the [Context Broker]{.HTML-Keyboard} shall apply a compaction operation as + defined by the JSON-LD specification [n.8], section 4.1.5 over both payload + and query parameters using the JSON-LD Context supplied in the value of the + ["jsonldContext"]{.HTML-Code} key-value pair, prior to distributing the + request to the context source endpoint and forwarding with this JSON-LD + context using an appropriate binding. Additionally, if a payload is defined in + the initial request to the [Context Broker]{.HTML-Keyboard}, the + ["Content-Type"]{.HTML-Code} of the forwarded request shall be + ["application/json"]{.HTML-Code} and the [Context Broker]{.HTML-Keyboard} + shall remove any _`@context`_ members from the payload prior to distributing + the request to the context source endpoint. + +If the key ["ngsildConformance"]{.HTML-Code} is defined: + +- The value shall define in the form major.minor, for example [1.5]{.HTML-Code}. +- The [Context Broker]{.HTML-Keyboard} shall apply a backwards compatibility + operation over the payload (as defined by Clause+++clause-9+++9.5.3) prior to + distributing the request to the context source endpoint such that the + forwarded payload conforms to the specified version of the NGSI-LD + specification. + +### 9.5.3 Backwards compatibility of Context Source payloads + +When retrieving Entity data found distributed across multiple associated +[Context Brokers]{.HTML-Keyboard} each [Context Source]{.HTML-Keyboard} is sent +a **context consumption** request. A [Context Broker]{.HTML-Keyboard} shall +assume that every [Context Source]{.HTML-Keyboard} will return valid NGSI-LD +Entity data in a format that it understands and it shall reject data that is +invalid. However, since the definition of a valid NGSI-LD Entity has broadened +with each version of the NGSI-LD specification, it is possible that a registered +[Context Source]{.HTML-Keyboard} could respond with valid NGSI-LD Entity data +which does not fit the narrower confines of a previous NGSI-LD specification. + +Therefore, when making a **context consumption** request, a [Context +Broker]{.HTML-Keyboard} may wish to indicate that it is only capable of +interpreting responses which conform to a specific NGSI-LD specification, in +which case the [Context Source]{.HTML-Keyboard} shall endeavour to amend its +payload accordingly. Table+++below describes a minimal level of support for a +NGSI-LD Entity data as specified by each version of the NGSI-LD specification, +and the expected fallback behaviour required if a **context consumption** +request is made to receive data conformant to an earlier version of the NGSI-LD +specification. Table+++9.5.3-2 describes conformance fallbacks for an NGSI-LD +Property (and its subclasses) and Table+++9.5.3-3 describes conformance +fallbacks for an NGSI-LD Relationship (and its subclasses). + +The version of the NGSI-LD specification requested and the conformant version +returned is defined in the form major.minor, for example [1.5]{.HTML-Code}. + + + +::: TH +Table: NGSI-LD Entity data type attribute support +::: + +::: TAL ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| Name | Data Type | Definition | Version | Conformant Data Fallback | +| | | | | | +| | | | Introduced | | ++=============================================================================+=============================================================================+==================================================================================+:===========================================================================:+=============================================================================+ +| id | String | Valid URI | 1.0 | | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| type | String or String[] (see note 1) | | 1.0 | | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| expiresAt | String | _DateTime_ as mandated by Clause+++clause-5+++5.2.2.4 | 1.9 | Remove attribute from payload | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| location | GeoProperty | Default geospatial Property of an entity. See Clause+++clause-5+++5.2.6.4.5 | 1.0 | | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| observationSpace | GeoProperty | See Clause+++clause-5+++5.2.6.4.5 | 1.0 | | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| operationSpace | GeoProperty | See Clause+++clause-5+++5.2.6.4.5 | 1.0 | | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| scope | String or String[] | See Clause+++clause-5+++5.2.7 | 1.4 | Remove attribute from payload | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| <​Attribute name> | Property or Property[] (see note 2) | _Property_ as mandated by Clause+++clause-5+++5.2.6.4.3 | 1.0 | | +| +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| | GeoProperty or GeoProperty[] (see note 2) | _GeoProperty_ as mandated by Clause+++clause-5+++5.2.6.4.5 | 1.0 | | +| +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| | LanguageProperty or LanguageProperty[] (see note 2) | _LanguageProperty_ as mandated by Clause+++clause-5+++5.2.6.4.6 | 1.4 | Reformat attribute as Property | +| +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| | JsonProperty or JsonProperty[] (see note 2) | _JsonProperty_ as mandated by Clause+++clause-5+++5.2.6.4.10 | 1.8 | Reformat attribute as Property | +| +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| | VocabProperty or VocabProperty[] (see note 2) | _VocabProperty_ as mandated by Clause+++clause-5+++5.2.6.4.7 | 1.8 | Reformat attribute as Property | +| +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| | ListProperty or ListProperty[] (see note 2) | _ListProperty_ as mandated by Clause+++clause-5+++5.2.6.4.8 | 1.8 | Reformat attribute as Property | +| +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| | Relationship | _Relationship_ as mandated by Clause+++clause-5+++5.2.6.4.4 | 1.0 | | +| | | | | | +| | or Relationship[] (see note 2) | | | | +| +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| | ListRelationship or ListRelationship[] (see note 2) | _ListRelationship_ as mandated by Clause+++clause-5+++5.2.6.4.9 | 1.8 | Reformat attribute as Relationship | ++-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------------------------------------------------------------------------+ +| >>> [!note] NOTE 1: | +| | +| From 1.3 onwards, an Entity _`type`_ can be assigned multiple values. For 1.0 backwards compatibility only return a single element with preference to the first instance. | +| | +| >>> | +| | +| >>> [!note] NOTE 2: | +| | +| From 1.3 onwards, multiple instances of each _Property_, _Relationship_, or subclasses thereof, identified by the same Attribute name, can be separated by _`datasetId`_. For 1.0 backwards compatibility only return a single element of the Array with preference to the default instance. | +| | +| >>> | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: NGSI-LD Property data type attribute support +::: + +::: TAL ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| Name | Data Type | Definition | Version Introduced | Conformant Data Fallback | ++=============+====================================================+===========================================================================+:==================:+===============================+ +| type | String | | 1.0 | | ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| value | Any JSON value as defined by IETF RFC 8259 [n.3] | See NGSI-LD Value definition in clause 3.1 | 1.0 | | ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| datasetId | String | Valid URI as mandated by Clause+++clause-8+++8.5 | 1.3 | Remove attribute from payload | ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| expiresAt | String | _DateTime_ as mandated by Clause+++clause-5+++5.2.2.4 | 1.9 | Remove attribute from payload | ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| observedAt | String | _DateTime_ as mandated by Clause+++clause-5+++5.2.2.4 | 1.3 | Remove attribute from payload | ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| unitCode | String | As mandated by [n.10] | 1.3 | Remove attribute from payload | ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| valueType | String | See Clause+++clause-5+++5.2.6.4 | 1.9 | Remove attribute from payload | ++-------------+----------------------------------------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +::: + + + + + +::: TH +Table: NGSI-LD Relationship data type attribute support +::: + +::: TAL ++-------------+----------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| Name | Data Type | Definition | Version Introduced | Conformant Data Fallback | ++=============+======================+===========================================================================+:==================:+===============================+ +| type | String | Valid URI | 1.0 | | ++-------------+----------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| object | String or String[] | | 1.0 | | ++-------------+----------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| datasetId | String | Valid URI as mandated by Clause+++clause-8+++8.5 | 1.3 | Remove attribute from payload | ++-------------+----------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| expiresAt | String | _DateTime_ as mandated by Clause+++clause-5+++5.2.2.4 | 1.9 | Remove attribute from payload | ++-------------+----------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| objectType | String or String[] | See Clause+++clause-5+++5.2.6.4.4 | 1.8 | Remove attribute from payload | ++-------------+----------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +| observedAt | String | _DateTime_ as mandated by Clause+++clause-5+++5.2.2.4 | 1.3 | Remove attribute from payload | ++-------------+----------------------+---------------------------------------------------------------------------+--------------------+-------------------------------+ +::: + + + +When responding to a **context consumption** request to supply data conforming +to a specific NGSI-LD specification, [Context Sources]{.HTML-Keyboard} should +indicate the version of the specification the returned payload **actually +conforms to**. In general, [Context Sources]{.HTML-Keyboard} will not be +expected to be flexible enough to supply payloads conformant to all past and +future versions of the specification, but the requesting [Context +Broker]{.HTML-Keyboard} may use supplied version information when collating data +from multiple [Context Sources]{.HTML-Keyboard} to validate and amend received +payloads. + +## 9.6 Querying and retrieving distributed Entities as unitary operations - Entity Maps + +[Context Broker]{.HTML-Keyboard} architectures assume that Entity data does not +need to be centralized within a single [Context Broker]{.HTML-Keyboard}, +however, when querying context information, Entity data retrieval can be +considered as a unitary operation, masking the fact that each registered +[Context Broker]{.HTML-Keyboard} is receiving a separate distributed **Context +Consumption** request. + +To process each **Context Consumption** request efficiently, and to support +consistent pagination, it is necessary for the [Context Broker]{.HTML-Keyboard} +to initially make a broad request to each registered **Context Source** whose +registration is matching the request. + +In the case of a **query Entities operation** (Clause+++clause-10+++10.4.3) or +**query Temporal Evolution of Entities operation** +(Clause+++clause-11+++11.3.3), a list of Entity identifiers is returned and +stored together with the registration information in an Entity map. Only the +Entities whose identifiers are contained in the Entity map are considered when +rendering the result pages. Filtering based on queries, geoqueries, scope +queries or attribute filters, as provided in the original query request, is +applied to the Entities before adding the Entity to a result page, i.e. +identifiers of Entities not matching the filters at the time of checking are +removed from the Entity map. + +In the case of a **retrieve Entity operation** (Clause+++clause-10+++10.4.2) or +**retrieve Temporal Evolution of an Entity operation** +(Clause+++clause-11+++11.3.2), an Entity map can be used to make subsequent +retrievals of the same Entity more efficient, as the Entity map provides the +information about which Context Source(s) store relevant Entity information, and +other [Context Sources]{.HTML-Keyboard} do not have to be considered. + +In the case that a client wishes to indicate to a [Context +Broker]{.HTML-Keyboard} that a request is part of a unitary sequence of +requests, the [Context Broker]{.HTML-Keyboard} shall create and cache an [Entity +Map]{.HTML-Keyboard} for future use and should return the location of said +[Entity Map]{.HTML-Keyboard} in a specific field. The caching strategy and +expiry time shall take into account a suggested expiry time, if present, and +depend on implementation specific configurations. [Context +Sources]{.HTML-Keyboard} should indicate that they do not support [Entity +Maps]{.HTML-Keyboard}, through declining to return the location of an [Entity +Map]{.HTML-Keyboard} when requested to do so. + +This Entity mapping is an internal operation, not usually exposed to the end +user, however it is necessary to explicitly define a consistent mechanism for +Entity map creation, caching and retrieval. + +A specific field pointing to the location of a cached [Entity +Map]{.HTML-Keyboard} (e.g. a custom header in the response in case of HTTP +binding, see [i.16] ~table 7.2.3.1-2) shall be returned within the response of a +query, whenever this is requested by the client. Similarly, the reuse of a +previously created [Entity Map]{.HTML-Keyboard} can be requested by passing the +same specific field into a request. + +If a subsequent request references an existent [Entity Map]{.HTML-Keyboard}, it +shall be used for the purposes of Entity registration matching, and queries +shall be filtered to only consider the Entities listed. Subsequent requests +referencing an [Entity Map]{.HTML-Keyboard} shall use the same parameters as in +the original request that created the [Entity Map]{.HTML-Keyboard}, except for +the specification of Entity identifiers or parameters related to pagination, or, +in the case of temporal requests, the temporal query. If an [Entity +Map]{.HTML-Keyboard} has expired, or cannot be accessed, no inference can be +made as to which entities are held within the [Context Sources]{.HTML-Keyboard} +and a new one shall be created. An [Entity Map]{.HTML-Keyboard} fixes the +Entities to be considered for subsequent requests based on it. The creating +[Context Source]{.HTML-Keyboard} shall remove Entities from the [Entity +Map]{.HTML-Keyboard} that do not match the filters of the query at the time of +processing. Other components shall only be allowed to update the expiry +timestamp of the [Entity Map]{.HTML-Keyboard}, which can optionally be extended +if the [Context Sources]{.HTML-Keyboard} implementation allows for it. + +Since an **exclusive** [Context Source Registration]{.HTML-Keyboard} already +specifies that all context data is held in a single location, its relevance to a +distributed query can be inferred within the Registered Context Source without +the use of an [Entity Map]{.HTML-Keyboard}. + +When executing **Context Consumption** or **Subscription** operations, a +significant optimization in performance can be achieved if it is known a priori +whether individual Entities are themselves distributed among [Context +Brokers]{.HTML-Keyboard} and [Context Sources]{.HTML-Keyboard}, or if each +[Context Broker]{.HTML-Keyboard} and [Context Source]{.HTML-Keyboard} always +stores complete Entities. In the latter case all parameters used for filtering +such as queries, geoqueries, scope queries or attribute filters can be forwarded +and applied locally, whereas in the former case, the Entity first has to be +assembled by the [Context Broker]{.HTML-Keyboard} and only then the filtering +can be applied. Since being able to apply filters locally is significantly more +efficient, a parameter can indicate that, for the given request, only Entities +are to be expected that are stored in their entirety on each [Context +Broker]{.HTML-Keyboard} and each [Context Sources]{.HTML-Keyboard}, and there +are no Entities that are themselves stored in a distributed fashion. Such +Entities are also referred to as split Entities. [Context +Broker]{.HTML-Keyboard} implementations should enable configuring a default for +this parameter, so deployments where no split Entities are to be expected can +filter locally and thus be more efficient. + +In the case of split Entities, [Entity Maps]{.HTML-Keyboard} initially only +store "candidate Entities" as no filters could be applied, because only a part +of the Entity was available. In the process of pagination, the filters will be +(re-)checked. Any Entity not (or no longer) fulfilling the filter shall be +removed from the [Entity Map]{.HTML-Keyboard}. + +## 9.7 Limiting cascading distributed operations + +When creating a registration, it is unknown whether the requested data is held +at the distributed endpoint, or it is in turn distributed via further +registrations. It is necessary to include a binding-specific mechanism to +request operations only on the registered endpoint itself to avoid cascades of +an excessive lengths, duplicates or loops. + +Furthermore, it is not known if any distributed endpoints of a registered +[Context Source]{.HTML-Keyboard} are in turn reliant on previously encountered +[Context Sources]{.HTML-Keyboard} thus causing an infinite loop. Therefore, when +processing a distributed operation, a specific field listing all previously +encountered [Context Sources]{.HTML-Keyboard} (e.g. a Via header in the response +in case of HTTP binding (IETF RFC 7230 [n.12])) shall be passed as part of the +request and this field can be used to exclude duplicated sources from matching +as [Context Source Registration]{.HTML-Keyboard}. + +In the case of multi-tenancy (see Clause+++clause-7+++7.8) each +[Tenant]{.HTML-Keyboard} found within each registered [Context +Source]{.HTML-Keyboard} shall be considered separately. diff --git a/md/executive-summary.md b/md/executive-summary.md new file mode 100644 index 0000000000000000000000000000000000000000..1ca323042705e155208c7d40645d97a41b9fc4d3 --- /dev/null +++ b/md/executive-summary.md @@ -0,0 +1,9 @@ +# Executive summary + +The present document formally describes the NGSI-LD API Specification. The +NGSI-LD API allows users to provide, consume and subscribe to context +information in multiple scenarios and involving multiple stakeholders. Context +information is modelled as attributes (properties and relationships) of context +entities, also referred to as "digital twins", representing real-world assets. +It enables close to real-time access to information coming from many different +sources (not only IoT data sources). diff --git a/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..0082936d2ed3286383156c6684f3a7199fd0fc66 --- /dev/null +++ b/md/front-page.md @@ -0,0 +1,85 @@ +::: ZA +[ETSI TS 104 175 ]{.ondemand_CHAR_size_32}V0.0.1[(2025-10)]{.ondemand_CHAR_size_16} +::: + +::: ZT +Data Solutions (DATA); +::: + +::: ZT +NGSI-LD Core API +::: + +ETSI Logo + +::: ZB +***TECHNICAL SPECIFICATION*** +::: + +::: TAC +Reference + +DTS/DATA-00104175 + +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..cc32f21680ccd687447818b9308e53a6e31e79c3 --- /dev/null +++ b/md/introduction.md @@ -0,0 +1,25 @@ +# Introduction + +The present document defines the NGSI-LD API Specification. The NGSI-LD API +allows users to provide, consume and subscribe to context information in +multiple scenarios and involving multiple stakeholders. Context information is +modelled as attributes of context entities, also referred to as "digital twins", +representing real-world assets (e.g. a bus in a city or a luggage claim ticket). +Because of that, the NGSI-LD API is often used to bring standardized access to +digital twin data. + +The ongoing status of the NGSI-LD API can be found in [i.1]. + +The ETSI TC DATA has decided to use the name "NGSI-LD API". The rationale is to +reinforce the fact that the present document leverages on the former OMA NGSI 9 +and 10 interfaces [i.2] and FIWARE® NGSIv2 [i.3] to incorporate the +latest advances from Linked Data. + +Editor Note: Check and update the projects + +Most of the NGSI-LD API and the previous ETSI ISG CIM information model work +referenced here was created with the support of the following European Union +Horizon 2020 research projects: No. 732851 (FI-NEXT), No. 723156 (WISE-IoT), No. +732240 (SynchroniCity) and No. 731993 (AutoPilot), No. 814918 (Fed4IoT), No. +779852 (IoTCrawler), No. 731884 (IoF2020), including many contributions from +members of the FIWARE® Community. diff --git a/md/media/.gitkeep b/md/media/.gitkeep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/md/media/Clause-4-Distributed-Operations.emf b/md/media/Clause-4-Distributed-Operations.emf new file mode 100644 index 0000000000000000000000000000000000000000..bf95bd454e3ff743ed08717c958283b518fcc1d6 Binary files /dev/null and b/md/media/Clause-4-Distributed-Operations.emf differ diff --git a/md/media/Clause-4-Distributed-Operations.png b/md/media/Clause-4-Distributed-Operations.png new file mode 100644 index 0000000000000000000000000000000000000000..4dde4ade8cdf7838ab92f11b56e1b3bff90de9a6 Binary files /dev/null and b/md/media/Clause-4-Distributed-Operations.png differ 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/image10.png b/md/media/image10.png new file mode 100644 index 0000000000000000000000000000000000000000..bbba81a69bb4f12f2a210f7eefac1d91fbf71d66 Binary files /dev/null and b/md/media/image10.png differ diff --git a/md/media/image11.png b/md/media/image11.png new file mode 100644 index 0000000000000000000000000000000000000000..26a60b67c923275152efadb4e4738b71d54fe9a1 Binary files /dev/null and b/md/media/image11.png differ diff --git a/md/media/image12.emf b/md/media/image12.emf new file mode 100644 index 0000000000000000000000000000000000000000..fdd3ae3f58cc939c81a2d912acc5aaebc53ddd74 Binary files /dev/null and b/md/media/image12.emf differ diff --git a/md/media/image12.png b/md/media/image12.png new file mode 100644 index 0000000000000000000000000000000000000000..87617b5218abda68741e668ade7934b0ef2dcdb6 Binary files /dev/null and b/md/media/image12.png differ diff --git a/md/media/image13.png b/md/media/image13.png new file mode 100644 index 0000000000000000000000000000000000000000..34b7981d526417aa327445faa6904895abe1bb00 Binary files /dev/null and b/md/media/image13.png differ diff --git a/md/media/image14.png b/md/media/image14.png new file mode 100644 index 0000000000000000000000000000000000000000..61e0e6d887efd11c122e8fe8f51dc3e9b1dcdc43 Binary files /dev/null and b/md/media/image14.png differ diff --git a/md/media/image143.emf b/md/media/image143.emf new file mode 100644 index 0000000000000000000000000000000000000000..d71cf3850239304cac007cb363b6ce0af1692c62 Binary files /dev/null and b/md/media/image143.emf differ diff --git a/md/media/image143.png b/md/media/image143.png new file mode 100644 index 0000000000000000000000000000000000000000..96a1e9bd2824c2536410c4d08503f3721504b090 Binary files /dev/null and b/md/media/image143.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.emf b/md/media/image145.emf new file mode 100644 index 0000000000000000000000000000000000000000..dc4b8eff8b5405bd6daa053410b090040f005850 Binary files /dev/null and b/md/media/image145.emf 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/image15.png b/md/media/image15.png new file mode 100644 index 0000000000000000000000000000000000000000..a394c4769228d82d0ea21e8002ce500c6cf6053f Binary files /dev/null and b/md/media/image15.png differ diff --git a/md/media/image16.emf b/md/media/image16.emf new file mode 100644 index 0000000000000000000000000000000000000000..e562b6280c3a32d8aae74eb3aaf28efbda36a80c Binary files /dev/null and b/md/media/image16.emf differ diff --git a/md/media/image16.png b/md/media/image16.png new file mode 100644 index 0000000000000000000000000000000000000000..1415af1f55def6b528151a2dcd34cfbf8ba1cf1d Binary files /dev/null and b/md/media/image16.png differ diff --git a/md/media/image17.emf b/md/media/image17.emf new file mode 100644 index 0000000000000000000000000000000000000000..4b0edc4f03b9be65c27efab0192b38caca27849c Binary files /dev/null and b/md/media/image17.emf differ diff --git a/md/media/image17.png b/md/media/image17.png new file mode 100644 index 0000000000000000000000000000000000000000..e9f1047b62c35cd57ac015c284fee13379b62bde Binary files /dev/null and b/md/media/image17.png differ diff --git a/md/media/image18.emf b/md/media/image18.emf new file mode 100644 index 0000000000000000000000000000000000000000..753a6b1483a9b8fb1c30d3fd23fbdd5932e2719a Binary files /dev/null and b/md/media/image18.emf differ diff --git a/md/media/image18.png b/md/media/image18.png new file mode 100644 index 0000000000000000000000000000000000000000..a7f7ae37b9dbfe4e8069e8d11e6778b5a18b2f72 Binary files /dev/null and b/md/media/image18.png differ diff --git a/md/media/image19.emf b/md/media/image19.emf new file mode 100644 index 0000000000000000000000000000000000000000..367f0f92f2817a01a2db1eed39b8d964851a0c04 Binary files /dev/null and b/md/media/image19.emf differ diff --git a/md/media/image19.png b/md/media/image19.png new file mode 100644 index 0000000000000000000000000000000000000000..f912a4709f0bb101087590be5c616a1987ed8a1f Binary files /dev/null and b/md/media/image19.png differ diff --git a/md/media/image2.emf b/md/media/image2.emf new file mode 100644 index 0000000000000000000000000000000000000000..abe072b7d0846b5b4485c7cc8d250bd300f40b76 Binary files /dev/null and b/md/media/image2.emf differ diff --git a/md/media/image2.png b/md/media/image2.png new file mode 100644 index 0000000000000000000000000000000000000000..84b0cf11788e8cd9a5b8c6230e02e7ccb421b550 Binary files /dev/null and b/md/media/image2.png differ diff --git a/md/media/image20.emf b/md/media/image20.emf new file mode 100644 index 0000000000000000000000000000000000000000..c8abea18215586ea398875b147f14e1201c4f248 Binary files /dev/null and b/md/media/image20.emf differ diff --git a/md/media/image20.png b/md/media/image20.png new file mode 100644 index 0000000000000000000000000000000000000000..cde23c195849ea91345364c03cbddf40108661c4 Binary files /dev/null and b/md/media/image20.png differ diff --git a/md/media/image21.emf b/md/media/image21.emf new file mode 100644 index 0000000000000000000000000000000000000000..2888ee6a0a7dc57afa80a5d5d32cb79a5d65385d Binary files /dev/null and b/md/media/image21.emf differ diff --git a/md/media/image21.png b/md/media/image21.png new file mode 100644 index 0000000000000000000000000000000000000000..b4dac32ccee7dd0bffeb8eb9dd66718495f3603f Binary files /dev/null and b/md/media/image21.png differ diff --git a/md/media/image22.emf b/md/media/image22.emf new file mode 100644 index 0000000000000000000000000000000000000000..935beadbca9b01f35245a450ca64006ea85d4e70 Binary files /dev/null and b/md/media/image22.emf differ diff --git a/md/media/image22.png b/md/media/image22.png new file mode 100644 index 0000000000000000000000000000000000000000..76cb3152ec9dcdc0d106ba58fc3a45092a7141d7 Binary files /dev/null and b/md/media/image22.png differ diff --git a/md/media/image23.emf b/md/media/image23.emf new file mode 100644 index 0000000000000000000000000000000000000000..1277f95f48898cc90c8ac10a74a1c040cd9cec9f Binary files /dev/null and b/md/media/image23.emf differ diff --git a/md/media/image23.png b/md/media/image23.png new file mode 100644 index 0000000000000000000000000000000000000000..7aba2aa97219aaa45612c6925379b81bb2ccafa1 Binary files /dev/null and b/md/media/image23.png differ diff --git a/md/media/image24.emf b/md/media/image24.emf new file mode 100644 index 0000000000000000000000000000000000000000..80d9e43a98845e482238a4e347c89899dde0ea40 Binary files /dev/null and b/md/media/image24.emf differ diff --git a/md/media/image24.png b/md/media/image24.png new file mode 100644 index 0000000000000000000000000000000000000000..e51562fd86f5a77075bcdc4d4083b5e78bbea85d Binary files /dev/null and b/md/media/image24.png differ diff --git a/md/media/image25.emf b/md/media/image25.emf new file mode 100644 index 0000000000000000000000000000000000000000..e46a500f8c26b19cdc6200832a29105fb3eda340 Binary files /dev/null and b/md/media/image25.emf differ diff --git a/md/media/image25.png b/md/media/image25.png new file mode 100644 index 0000000000000000000000000000000000000000..c0852c5dd81187f4e374f1bf403d12fe57ed538c Binary files /dev/null and b/md/media/image25.png differ diff --git a/md/media/image26.emf b/md/media/image26.emf new file mode 100644 index 0000000000000000000000000000000000000000..b58b5f72b124a4443308208f1a7af87ee80b8aa8 Binary files /dev/null and b/md/media/image26.emf differ diff --git a/md/media/image26.png b/md/media/image26.png new file mode 100644 index 0000000000000000000000000000000000000000..669565c1198a30dd2f017c8c8de1108cdeb859d9 Binary files /dev/null and b/md/media/image26.png differ diff --git a/md/media/image27.emf b/md/media/image27.emf new file mode 100644 index 0000000000000000000000000000000000000000..c0cbdd10281917accc8b57e29237bab48652a1f4 Binary files /dev/null and b/md/media/image27.emf differ diff --git a/md/media/image27.png b/md/media/image27.png new file mode 100644 index 0000000000000000000000000000000000000000..1e957ed4c2e56cfae5237eac118832ef914245fc Binary files /dev/null and b/md/media/image27.png differ diff --git a/md/media/image28.emf b/md/media/image28.emf new file mode 100644 index 0000000000000000000000000000000000000000..28c87d76834fa9ee5219c193ea898801ac7708c5 Binary files /dev/null and b/md/media/image28.emf differ diff --git a/md/media/image28.png b/md/media/image28.png new file mode 100644 index 0000000000000000000000000000000000000000..08a2becf4c400894807dea87fe38fae8bbb1be93 Binary files /dev/null and b/md/media/image28.png differ diff --git a/md/media/image29.emf b/md/media/image29.emf new file mode 100644 index 0000000000000000000000000000000000000000..cb7f6da17147a63092a84e2e9bb1f003ad701fb2 Binary files /dev/null and b/md/media/image29.emf differ diff --git a/md/media/image29.png b/md/media/image29.png new file mode 100644 index 0000000000000000000000000000000000000000..edf5ffdf3b400db02ea046a7544efdf924e0ef98 Binary files /dev/null and b/md/media/image29.png differ diff --git a/md/media/image3.emf b/md/media/image3.emf new file mode 100644 index 0000000000000000000000000000000000000000..615a7ad370c2a82b72ff0909ff191394842aac82 Binary files /dev/null and b/md/media/image3.emf differ diff --git a/md/media/image3.png b/md/media/image3.png new file mode 100644 index 0000000000000000000000000000000000000000..6c485547f49308adf0eff77f460d8e4ddf43b5db Binary files /dev/null and b/md/media/image3.png differ diff --git a/md/media/image30.emf b/md/media/image30.emf new file mode 100644 index 0000000000000000000000000000000000000000..fcbce4c1702fa1ec013acd61405dd96bee2f489f Binary files /dev/null and b/md/media/image30.emf differ diff --git a/md/media/image30.png b/md/media/image30.png new file mode 100644 index 0000000000000000000000000000000000000000..578d576a6f324813946bce94beeb1f70afa928ba Binary files /dev/null and b/md/media/image30.png differ diff --git a/md/media/image31.emf b/md/media/image31.emf new file mode 100644 index 0000000000000000000000000000000000000000..e938f2493e42c5780dd70ea5fa2c9f90ad3531d7 Binary files /dev/null and b/md/media/image31.emf differ diff --git a/md/media/image31.png b/md/media/image31.png new file mode 100644 index 0000000000000000000000000000000000000000..4950301ff0506ffaae05867640608eb35ea85496 Binary files /dev/null and b/md/media/image31.png differ diff --git a/md/media/image32.emf b/md/media/image32.emf new file mode 100644 index 0000000000000000000000000000000000000000..fabe8562e999d1b52ff54060d8f0dae683c04bb4 Binary files /dev/null and b/md/media/image32.emf differ diff --git a/md/media/image32.png b/md/media/image32.png new file mode 100644 index 0000000000000000000000000000000000000000..22911723d8b719371f88e5b4fcba6db955524f7c Binary files /dev/null and b/md/media/image32.png differ diff --git a/md/media/image33.emf b/md/media/image33.emf new file mode 100644 index 0000000000000000000000000000000000000000..a989d041ad731e503a4f4158b7fcea0ce63cd894 Binary files /dev/null and b/md/media/image33.emf differ diff --git a/md/media/image33.png b/md/media/image33.png new file mode 100644 index 0000000000000000000000000000000000000000..b6095635c603094f2dea587a3301916ab011e80e Binary files /dev/null and b/md/media/image33.png differ diff --git a/md/media/image34.emf b/md/media/image34.emf new file mode 100644 index 0000000000000000000000000000000000000000..dc6b38aba0bbfd28848fd4bf86de29c8e0a754a7 Binary files /dev/null and b/md/media/image34.emf differ diff --git a/md/media/image34.png b/md/media/image34.png new file mode 100644 index 0000000000000000000000000000000000000000..d4397218f44dc47eec79f852b150fb774cd4f6dd Binary files /dev/null and b/md/media/image34.png differ diff --git a/md/media/image35.emf b/md/media/image35.emf new file mode 100644 index 0000000000000000000000000000000000000000..56da719c7f4eefce58b26edc1656621ea6b25af6 Binary files /dev/null and b/md/media/image35.emf differ diff --git a/md/media/image35.png b/md/media/image35.png new file mode 100644 index 0000000000000000000000000000000000000000..9e0e964511a1daf78aaf395b57aea66faa363ba9 Binary files /dev/null and b/md/media/image35.png differ diff --git a/md/media/image36.emf b/md/media/image36.emf new file mode 100644 index 0000000000000000000000000000000000000000..da5500ba46813441aafa727f0131b8756228df93 Binary files /dev/null and b/md/media/image36.emf differ diff --git a/md/media/image36.png b/md/media/image36.png new file mode 100644 index 0000000000000000000000000000000000000000..0d4cebb6319538ea046fdd34ee36338704690899 Binary files /dev/null and b/md/media/image36.png differ diff --git a/md/media/image37.emf b/md/media/image37.emf new file mode 100644 index 0000000000000000000000000000000000000000..24f01e6c31c7263ed472081bee584f526d809b24 Binary files /dev/null and b/md/media/image37.emf differ diff --git a/md/media/image37.png b/md/media/image37.png new file mode 100644 index 0000000000000000000000000000000000000000..1eced511439f1f769fe9c2b22d5fac44e2f09abe Binary files /dev/null and b/md/media/image37.png differ diff --git a/md/media/image38.emf b/md/media/image38.emf new file mode 100644 index 0000000000000000000000000000000000000000..23bf598d00e567784e3ace345e92847b347266b1 Binary files /dev/null and b/md/media/image38.emf differ diff --git a/md/media/image38.png b/md/media/image38.png new file mode 100644 index 0000000000000000000000000000000000000000..43d40121d1fd8014acf3f3fa4f5cfe327be0c32e Binary files /dev/null and b/md/media/image38.png differ diff --git a/md/media/image39.emf b/md/media/image39.emf new file mode 100644 index 0000000000000000000000000000000000000000..85e143becd31d657905c50bfff0649b78f9081b9 Binary files /dev/null and b/md/media/image39.emf differ diff --git a/md/media/image39.png b/md/media/image39.png new file mode 100644 index 0000000000000000000000000000000000000000..1b9d4603953e26459b3bc4a976b07fe6ce5b767f Binary files /dev/null and b/md/media/image39.png differ diff --git a/md/media/image4.png b/md/media/image4.png new file mode 100644 index 0000000000000000000000000000000000000000..b6daa9eded7394c1adf47d885a9f50a52076e756 Binary files /dev/null and b/md/media/image4.png differ diff --git a/md/media/image40.emf b/md/media/image40.emf new file mode 100644 index 0000000000000000000000000000000000000000..3cc75bf45fc048ad1ee1e0c29b9f7bbe3182403b Binary files /dev/null and b/md/media/image40.emf differ diff --git a/md/media/image40.png b/md/media/image40.png new file mode 100644 index 0000000000000000000000000000000000000000..7f36b28107f4cb2c2e5abb2d8631b4c8a1bf6ec1 Binary files /dev/null and b/md/media/image40.png differ diff --git a/md/media/image41.emf b/md/media/image41.emf new file mode 100644 index 0000000000000000000000000000000000000000..dcce16d909c52bcf606a40772d6baf63eb181214 Binary files /dev/null and b/md/media/image41.emf differ diff --git a/md/media/image41.png b/md/media/image41.png new file mode 100644 index 0000000000000000000000000000000000000000..fe5f525d0d9a5e5804cb2767ccfee142ec31cdeb Binary files /dev/null and b/md/media/image41.png differ diff --git a/md/media/image42.emf b/md/media/image42.emf new file mode 100644 index 0000000000000000000000000000000000000000..f5ea73679bfe7636d1ccf2344e163c2aca9a9222 Binary files /dev/null and b/md/media/image42.emf differ diff --git a/md/media/image42.png b/md/media/image42.png new file mode 100644 index 0000000000000000000000000000000000000000..a82d9974d269194a829d830b88b162115ca37fbc Binary files /dev/null and b/md/media/image42.png differ diff --git a/md/media/image43.emf b/md/media/image43.emf new file mode 100644 index 0000000000000000000000000000000000000000..ae65218ae7d80ecf5b7d23c58be08e37d0e53393 Binary files /dev/null and b/md/media/image43.emf differ diff --git a/md/media/image43.png b/md/media/image43.png new file mode 100644 index 0000000000000000000000000000000000000000..3420b2045318b87121720d321c4035dd12965d99 Binary files /dev/null and b/md/media/image43.png differ diff --git a/md/media/image44.emf b/md/media/image44.emf new file mode 100644 index 0000000000000000000000000000000000000000..aae976f1317c307ef3df15f8353497593da77dc2 Binary files /dev/null and b/md/media/image44.emf differ diff --git a/md/media/image44.png b/md/media/image44.png new file mode 100644 index 0000000000000000000000000000000000000000..b79f07df89ebfcc7208b7856b9c621ef11de98e4 Binary files /dev/null and b/md/media/image44.png differ diff --git a/md/media/image45.emf b/md/media/image45.emf new file mode 100644 index 0000000000000000000000000000000000000000..09e400b9aed06a96565df204bb1f1f17e3cc3cae Binary files /dev/null and b/md/media/image45.emf differ diff --git a/md/media/image45.png b/md/media/image45.png new file mode 100644 index 0000000000000000000000000000000000000000..0e46d01c148c36992fecb0281c08a29f38cb457c Binary files /dev/null and b/md/media/image45.png differ diff --git a/md/media/image46.emf b/md/media/image46.emf new file mode 100644 index 0000000000000000000000000000000000000000..841b5e7d03c850ecc1dcd278d85148929a3bea79 Binary files /dev/null and b/md/media/image46.emf differ diff --git a/md/media/image46.png b/md/media/image46.png new file mode 100644 index 0000000000000000000000000000000000000000..48df662bf6aef922df004eafb9987a672ceff7df Binary files /dev/null and b/md/media/image46.png differ diff --git a/md/media/image47.emf b/md/media/image47.emf new file mode 100644 index 0000000000000000000000000000000000000000..ed62acbd2d21c2731fdbf46384ce09554f0c027d Binary files /dev/null and b/md/media/image47.emf differ diff --git a/md/media/image47.png b/md/media/image47.png new file mode 100644 index 0000000000000000000000000000000000000000..42d1ff713199ae37da6b542b2ec6eff9b4723503 Binary files /dev/null and b/md/media/image47.png differ diff --git a/md/media/image48.emf b/md/media/image48.emf new file mode 100644 index 0000000000000000000000000000000000000000..0242a218ddcf7f2b1526277ec9ab283c5eef289b Binary files /dev/null and b/md/media/image48.emf differ diff --git a/md/media/image48.png b/md/media/image48.png new file mode 100644 index 0000000000000000000000000000000000000000..91b590933cb0d7f7d431019221830d011cb9cec0 Binary files /dev/null and b/md/media/image48.png differ diff --git a/md/media/image49.emf b/md/media/image49.emf new file mode 100644 index 0000000000000000000000000000000000000000..d95d6484a2946967babd70f18a891c162e0573ff Binary files /dev/null and b/md/media/image49.emf differ diff --git a/md/media/image49.png b/md/media/image49.png new file mode 100644 index 0000000000000000000000000000000000000000..936958d5df2f1aadd6171816a4904a17c7168400 Binary files /dev/null and b/md/media/image49.png differ diff --git a/md/media/image5.png b/md/media/image5.png new file mode 100644 index 0000000000000000000000000000000000000000..8f7f89559a6b021f4d487cfccd009570ba91fa2f Binary files /dev/null and b/md/media/image5.png differ diff --git a/md/media/image50.emf b/md/media/image50.emf new file mode 100644 index 0000000000000000000000000000000000000000..a36adede6cceed871327e85ddf99be1ba6012215 Binary files /dev/null and b/md/media/image50.emf differ diff --git a/md/media/image50.png b/md/media/image50.png new file mode 100644 index 0000000000000000000000000000000000000000..17e01f1b83a68a4929d4cda8418796c657bf05aa Binary files /dev/null and b/md/media/image50.png differ diff --git a/md/media/image51.emf b/md/media/image51.emf new file mode 100644 index 0000000000000000000000000000000000000000..5aef69862552bd4adb05a4856cdb93bf4f6fae65 Binary files /dev/null and b/md/media/image51.emf differ diff --git a/md/media/image51.png b/md/media/image51.png new file mode 100644 index 0000000000000000000000000000000000000000..ec8316754a27133fd651749e75d9402219991015 Binary files /dev/null and b/md/media/image51.png differ diff --git a/md/media/image52.emf b/md/media/image52.emf new file mode 100644 index 0000000000000000000000000000000000000000..843b1a5fc6e55aaf5ea23d1d7a70c6920bdbf313 Binary files /dev/null and b/md/media/image52.emf differ diff --git a/md/media/image52.png b/md/media/image52.png new file mode 100644 index 0000000000000000000000000000000000000000..6e4c89646804abe6be5eb3fb7855cce28a862882 Binary files /dev/null and b/md/media/image52.png differ diff --git a/md/media/image53.emf b/md/media/image53.emf new file mode 100644 index 0000000000000000000000000000000000000000..e04741908addde9b301da022624556300a81f000 Binary files /dev/null and b/md/media/image53.emf differ diff --git a/md/media/image53.png b/md/media/image53.png new file mode 100644 index 0000000000000000000000000000000000000000..741bf3dfc4dcb9a86c5de9c4e34ac268ef5e812a Binary files /dev/null and b/md/media/image53.png differ diff --git a/md/media/image54.emf b/md/media/image54.emf new file mode 100644 index 0000000000000000000000000000000000000000..42fa375da9afc08a63d7709a7a194b7312e004c3 Binary files /dev/null and b/md/media/image54.emf differ diff --git a/md/media/image54.png b/md/media/image54.png new file mode 100644 index 0000000000000000000000000000000000000000..39d1c283be94bd9c5fcd8c42c3a29351e0a3be11 Binary files /dev/null and b/md/media/image54.png differ diff --git a/md/media/image55.emf b/md/media/image55.emf new file mode 100644 index 0000000000000000000000000000000000000000..f33862281376a1168e3ab2e66519258d1f017f54 Binary files /dev/null and b/md/media/image55.emf differ diff --git a/md/media/image55.png b/md/media/image55.png new file mode 100644 index 0000000000000000000000000000000000000000..f77720eb27e24d68512bc52532b43a90de4fc142 Binary files /dev/null and b/md/media/image55.png differ diff --git a/md/media/image56.emf b/md/media/image56.emf new file mode 100644 index 0000000000000000000000000000000000000000..50cc71666d109963d03af3b5f8e649da15094ac5 Binary files /dev/null and b/md/media/image56.emf differ diff --git a/md/media/image56.png b/md/media/image56.png new file mode 100644 index 0000000000000000000000000000000000000000..96ea898990d06cb64ee72de0e951db8ad67d9ebb Binary files /dev/null and b/md/media/image56.png differ diff --git a/md/media/image57.emf b/md/media/image57.emf new file mode 100644 index 0000000000000000000000000000000000000000..1695a2a6ee35eaca113b89e77a3df428e50602b6 Binary files /dev/null and b/md/media/image57.emf differ diff --git a/md/media/image57.png b/md/media/image57.png new file mode 100644 index 0000000000000000000000000000000000000000..3262103037c4bc28abc94328de49079478a1c309 Binary files /dev/null and b/md/media/image57.png differ diff --git a/md/media/image58.emf b/md/media/image58.emf new file mode 100644 index 0000000000000000000000000000000000000000..c029943eea1e6e3f20021c2364a4d1549b59407e Binary files /dev/null and b/md/media/image58.emf differ diff --git a/md/media/image58.png b/md/media/image58.png new file mode 100644 index 0000000000000000000000000000000000000000..4b581de77dfea9ef4cd7419f44d3a320597074bb Binary files /dev/null and b/md/media/image58.png differ diff --git a/md/media/image59.emf b/md/media/image59.emf new file mode 100644 index 0000000000000000000000000000000000000000..780ef2941d0c95e44f404c7db1681e2a147b847f Binary files /dev/null and b/md/media/image59.emf differ diff --git a/md/media/image59.png b/md/media/image59.png new file mode 100644 index 0000000000000000000000000000000000000000..956f2d54c1135b424436548c60645b392fab7116 Binary files /dev/null and b/md/media/image59.png differ diff --git a/md/media/image6.png b/md/media/image6.png new file mode 100644 index 0000000000000000000000000000000000000000..4207d96097ef081eb9e128b736c9add0322d9816 Binary files /dev/null and b/md/media/image6.png differ diff --git a/md/media/image60.emf b/md/media/image60.emf new file mode 100644 index 0000000000000000000000000000000000000000..8dbe359542299ee005c72d4858fce22d5108c109 Binary files /dev/null and b/md/media/image60.emf differ diff --git a/md/media/image60.png b/md/media/image60.png new file mode 100644 index 0000000000000000000000000000000000000000..d1d25671298cc5e3695a3f105e1271e5a18cad59 Binary files /dev/null and b/md/media/image60.png differ diff --git a/md/media/image61.emf b/md/media/image61.emf new file mode 100644 index 0000000000000000000000000000000000000000..bdce0efe264cb01bd03b46beacdcd59c19e47ce5 Binary files /dev/null and b/md/media/image61.emf differ diff --git a/md/media/image61.png b/md/media/image61.png new file mode 100644 index 0000000000000000000000000000000000000000..d13d84065ee039fb6bbb2272f6e192796e3d5c1b Binary files /dev/null and b/md/media/image61.png differ diff --git a/md/media/image62.emf b/md/media/image62.emf new file mode 100644 index 0000000000000000000000000000000000000000..ea2aff50e7eb5111e58bd1252a460126be5dde8e Binary files /dev/null and b/md/media/image62.emf differ diff --git a/md/media/image62.png b/md/media/image62.png new file mode 100644 index 0000000000000000000000000000000000000000..b82a96db61c021339161546f9009a38161dafbec Binary files /dev/null and b/md/media/image62.png differ diff --git a/md/media/image63.emf b/md/media/image63.emf new file mode 100644 index 0000000000000000000000000000000000000000..ed81571a1b1d72f02526ea19e4dfd1632be62aab Binary files /dev/null and b/md/media/image63.emf differ diff --git a/md/media/image63.png b/md/media/image63.png new file mode 100644 index 0000000000000000000000000000000000000000..93878606899e5748e46f7e729f539b4f82006c6b Binary files /dev/null and b/md/media/image63.png differ diff --git a/md/media/image64.emf b/md/media/image64.emf new file mode 100644 index 0000000000000000000000000000000000000000..1efc61fbe10c1ea976b70cec13a90d6c5d129f92 Binary files /dev/null and b/md/media/image64.emf differ diff --git a/md/media/image64.png b/md/media/image64.png new file mode 100644 index 0000000000000000000000000000000000000000..1d69d61ba5687387fb5170a7559b7cd871d41573 Binary files /dev/null and b/md/media/image64.png differ diff --git a/md/media/image65.emf b/md/media/image65.emf new file mode 100644 index 0000000000000000000000000000000000000000..6ce859b2ea388e66866fb1a7f2557887bdd8e8a0 Binary files /dev/null and b/md/media/image65.emf differ diff --git a/md/media/image65.png b/md/media/image65.png new file mode 100644 index 0000000000000000000000000000000000000000..dc963279644b1763735cc60bedaf11bcd24135f6 Binary files /dev/null and b/md/media/image65.png differ diff --git a/md/media/image66.emf b/md/media/image66.emf new file mode 100644 index 0000000000000000000000000000000000000000..168483655b5052777eda2b67566848988f230843 Binary files /dev/null and b/md/media/image66.emf differ diff --git a/md/media/image66.png b/md/media/image66.png new file mode 100644 index 0000000000000000000000000000000000000000..3aa375173fdd5fdb0f143e2b58f05cf86d1984c8 Binary files /dev/null and b/md/media/image66.png differ diff --git a/md/media/image67.emf b/md/media/image67.emf new file mode 100644 index 0000000000000000000000000000000000000000..62e38233c6f43ecc6691de9913b8fd480b7eff60 Binary files /dev/null and b/md/media/image67.emf differ diff --git a/md/media/image67.png b/md/media/image67.png new file mode 100644 index 0000000000000000000000000000000000000000..61a6aa551c88d1a3a1082634f3a47048ad4e2d4f Binary files /dev/null and b/md/media/image67.png differ diff --git a/md/media/image68.emf b/md/media/image68.emf new file mode 100644 index 0000000000000000000000000000000000000000..d8ccae6ad91b4a843eedc12a908dab2f23e31ba9 Binary files /dev/null and b/md/media/image68.emf differ diff --git a/md/media/image68.png b/md/media/image68.png new file mode 100644 index 0000000000000000000000000000000000000000..f5fc07193a0903f13a722fafa6b1cf83bcee3c51 Binary files /dev/null and b/md/media/image68.png differ diff --git a/md/media/image69.emf b/md/media/image69.emf new file mode 100644 index 0000000000000000000000000000000000000000..e24b37874213ca87d166e7441e2be5ec79e05ca9 Binary files /dev/null and b/md/media/image69.emf differ diff --git a/md/media/image69.png b/md/media/image69.png new file mode 100644 index 0000000000000000000000000000000000000000..be4e38f99e9291cac4af013fad66a17f67821a17 Binary files /dev/null and b/md/media/image69.png differ diff --git a/md/media/image7.png b/md/media/image7.png new file mode 100644 index 0000000000000000000000000000000000000000..1ebc42921dedfe0ae4273e1c3c190d14dfdb66fb Binary files /dev/null and b/md/media/image7.png differ diff --git a/md/media/image70.emf b/md/media/image70.emf new file mode 100644 index 0000000000000000000000000000000000000000..05c46e91c48f3ff5beb371e8f0830c9b36073f35 Binary files /dev/null and b/md/media/image70.emf differ diff --git a/md/media/image70.png b/md/media/image70.png new file mode 100644 index 0000000000000000000000000000000000000000..954d60606ae1cb4ed58ef8cdf72f5991879f28e3 Binary files /dev/null and b/md/media/image70.png differ diff --git a/md/media/image71.emf b/md/media/image71.emf new file mode 100644 index 0000000000000000000000000000000000000000..b3c11bb849d3679d8f058bf85f10c4ba4d9a24a6 Binary files /dev/null and b/md/media/image71.emf differ diff --git a/md/media/image71.png b/md/media/image71.png new file mode 100644 index 0000000000000000000000000000000000000000..f94707c00ca773c7359d16c00358c919413e044e Binary files /dev/null and b/md/media/image71.png differ diff --git a/md/media/image72.emf b/md/media/image72.emf new file mode 100644 index 0000000000000000000000000000000000000000..3b38bb711609ff572735193ea9389bae691678f7 Binary files /dev/null and b/md/media/image72.emf differ diff --git a/md/media/image72.png b/md/media/image72.png new file mode 100644 index 0000000000000000000000000000000000000000..dbb833b78e9083679d2fbc3111c2774d98e41cee Binary files /dev/null and b/md/media/image72.png differ diff --git a/md/media/image73.emf b/md/media/image73.emf new file mode 100644 index 0000000000000000000000000000000000000000..95b27fd9f1f5e3f5ef0b84b33f7e8c02e63a2ad8 Binary files /dev/null and b/md/media/image73.emf differ diff --git a/md/media/image73.png b/md/media/image73.png new file mode 100644 index 0000000000000000000000000000000000000000..71db966cb6747d0e9b56418cf2f7969da0b906bc Binary files /dev/null and b/md/media/image73.png differ diff --git a/md/media/image74.emf b/md/media/image74.emf new file mode 100644 index 0000000000000000000000000000000000000000..c21b83e29036b1caebbd87f33c6ef0682b59b2b9 Binary files /dev/null and b/md/media/image74.emf differ diff --git a/md/media/image74.png b/md/media/image74.png new file mode 100644 index 0000000000000000000000000000000000000000..58e42dee6d9bd0d3fc44e64fbc11cd5ec8c4a7c4 Binary files /dev/null and b/md/media/image74.png differ diff --git a/md/media/image75.emf b/md/media/image75.emf new file mode 100644 index 0000000000000000000000000000000000000000..8d12cc42f8d03b347af5da614cf7932be0a8f4df Binary files /dev/null and b/md/media/image75.emf differ diff --git a/md/media/image75.png b/md/media/image75.png new file mode 100644 index 0000000000000000000000000000000000000000..7e5764221604e03950303e3695956c4a4ed5cfa2 Binary files /dev/null and b/md/media/image75.png differ diff --git a/md/media/image76.emf b/md/media/image76.emf new file mode 100644 index 0000000000000000000000000000000000000000..fd3644ca0b5efb20a43cb9c4467643793d012ba3 Binary files /dev/null and b/md/media/image76.emf differ diff --git a/md/media/image76.png b/md/media/image76.png new file mode 100644 index 0000000000000000000000000000000000000000..513f3dd18d88a7834f6d605af2da012c9971700e Binary files /dev/null and b/md/media/image76.png differ diff --git a/md/media/image77.emf b/md/media/image77.emf new file mode 100644 index 0000000000000000000000000000000000000000..718b7e0846cf87a937614cd2886600f540b1a2cc Binary files /dev/null and b/md/media/image77.emf differ diff --git a/md/media/image77.png b/md/media/image77.png new file mode 100644 index 0000000000000000000000000000000000000000..4175d8e14f1045e960e6452c8ef34a99fe288847 Binary files /dev/null and b/md/media/image77.png differ diff --git a/md/media/image8.png b/md/media/image8.png new file mode 100644 index 0000000000000000000000000000000000000000..1eb2b1b30d09d7becb84d7cd07a1ea8284d91646 Binary files /dev/null and b/md/media/image8.png differ diff --git a/md/media/image9.png b/md/media/image9.png new file mode 100644 index 0000000000000000000000000000000000000000..bcf70d1d418fc056e62738c75865211110b71c8f Binary files /dev/null and b/md/media/image9.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.