diff --git a/md/annex-b.md b/md/annex-b.md index 23b52df999761cfa62bef744cfdb710008281c0b..906b222cf1a0170d47a71db45cf5a3dc7b530f22 100644 --- a/md/annex-b.md +++ b/md/annex-b.md @@ -216,6 +216,10 @@ Such definition has been tested using [i.19]. "TemporalProperty": "ngsi-ld:TemporalProperty", "Time": "ngsi-ld:Time", "VocabProperty": "ngsi-ld:VocabProperty", + "avg": { + "@id": "ngsi-ld:avg", + "@container": "@list" + }, "bbox": { "@container": "@list", "@id": "geojson:bbox" @@ -244,6 +248,10 @@ Such definition has been tested using [i.19]. }, "description": "http://purl.org/dc/terms/description", "detail": "ngsi-ld:detail", + "distinctCount": { + "@id": "ngsi-ld:distinctCount", + "@container": "@list" + }, "endpoint": { "@id": "ngsi-ld:endpoint", "@context": { @@ -303,17 +311,7 @@ Such definition has been tested using [i.19]. "jsonldContext": "ngsi-ld:jsonldContext", "jsons": { "@id": "ngsi-ld:jsons", - "@container": "@list", - "@context": { - "distinctCount": { - "@id": "ngsi-ld:distinctCount", - "@container": "@list" - }, - "totalCount": { - "@id": "ngsi-ld:totalCount", - "@container": "@list" - } - } + "@container": "@list" }, "key": "ngsi-ld:hasKey", "lang": "ngsi-ld:lang", @@ -323,17 +321,7 @@ Such definition has been tested using [i.19]. }, "languageMaps": { "@id": "ngsi-ld:hasLanguageMaps", - "@container": "@list", - "@context": { - "distinctCount": { - "@id": "ngsi-ld:distinctCount", - "@container": "@list" - }, - "totalCount": { - "@id": "ngsi-ld:totalCount", - "@container": "@list" - } - } + "@container": "@list" }, "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString", "lastUsedAt": { @@ -364,6 +352,14 @@ Such definition has been tested using [i.19]. } } }, + "max": { + "@id": "ngsi-ld:max", + "@container": "@list" + }, + "min": { + "@id": "ngsi-ld:min", + "@container": "@list" + }, "mode": "ngsi-ld:mode", "modifiedAt": { "@id": "ngsi-ld:modifiedAt", @@ -439,31 +435,11 @@ Such definition has been tested using [i.19]. }, "objectLists": { "@id": "ngsi-ld:hasObjectLists", - "@container": "@list", - "@context": { - "distinctCount": { - "@id": "ngsi-ld:distinctCount", - "@container": "@list" - }, - "totalCount": { - "@id": "ngsi-ld:totalCount", - "@container": "@list" - } - } + "@container": "@list" }, "objects": { "@id": "ngsi-ld:hasObjects", - "@container": "@list", - "@context": { - "distinctCount": { - "@id": "ngsi-ld:distinctCount", - "@container": "@list" - }, - "totalCount": { - "@id": "ngsi-ld:totalCount", - "@container": "@list" - } - } + "@container": "@list" }, "objectType": { "@id": "ngsi-ld:hasObjectType", @@ -553,11 +529,23 @@ Such definition has been tested using [i.19]. "@id": "ngsi-ld:snapshotTemporalQueriesDetails", "@container": "@list" }, + "stddev": { + "@id": "ngsi-ld:stddev", + "@container": "@list" + }, "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" + }, "temporalQ": { "@id": "ngsi-ld:temporalQ", "@context": { @@ -582,6 +570,10 @@ Such definition has been tested using [i.19]. "@id": "ngsi-ld:tenant", "@type": "@id" }, + "totalCount": { + "@id": "ngsi-ld:totalCount", + "@container": "@list" + }, "throttling": "ngsi-ld:throttling", "timeInterval": "ngsi-ld:timeInterval", "title": "http://purl.org/dc/terms/title", @@ -595,55 +587,11 @@ Such definition has been tested using [i.19]. }, "valueLists": { "@id": "ngsi-ld:hasValueLists", - "@container": "@list", - "@context": { - "distinctCount": { - "@id": "ngsi-ld:distinctCount", - "@container": "@list" - }, - "totalCount": { - "@id": "ngsi-ld:totalCount", - "@container": "@list" - } - } + "@container": "@list" }, "values": { "@id": "ngsi-ld:hasValues", - "@container": "@list", - "@context": { - "avg": { - "@id": "ngsi-ld:avg", - "@container": "@list" - }, - "distinctCount": { - "@id": "ngsi-ld:distinctCount", - "@container": "@list" - }, - "max": { - "@id": "ngsi-ld:max", - "@container": "@list" - }, - "min": { - "@id": "ngsi-ld:min", - "@container": "@list" - }, - "stddev": { - "@id": "ngsi-ld:stddev", - "@container": "@list" - }, - "sum": { - "@id": "ngsi-ld:sum", - "@container": "@list" - }, - "sumsq": { - "@id": "ngsi-ld:sumsq", - "@container": "@list" - }, - "totalCount": { - "@id": "ngsi-ld:totalCount", - "@container": "@list" - } - } + "@container": "@list" }, "valueType": { "@id": "ngsi-ld:hasValueType", @@ -655,17 +603,7 @@ Such definition has been tested using [i.19]. }, "vocabs": { "@id": "ngsi-ld:hasVocabs", - "@container": "@list", - "@context": { - "distinctCount": { - "@id": "ngsi-ld:distinctCount", - "@container": "@list" - }, - "totalCount": { - "@id": "ngsi-ld:totalCount", - "@container": "@list" - } - } + "@container": "@list" }, "watchedAttributes": { "@id": "ngsi-ld:watchedAttributes", diff --git a/md/annex-c.md b/md/annex-c.md index 4104efd10727f8735e82a037287a30041235620f..32339e4e3d16e38dfb87b2c03fa7455c291d65b6 100644 --- a/md/annex-c.md +++ b/md/annex-c.md @@ -1106,7 +1106,7 @@ level of the graph only. Below is an example, where temporal evolution of 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 combination of +_`datasetId`_ and both instances are represented in the array. The combination of an Attribute's _`datasetId`_ and the _`instanceId`_ associated to each value enables modification of a particular instance value without affecting instances from other sources. @@ -1118,50 +1118,46 @@ from other sources. "speed": [ { "type": "Property", - "values": [ - { - "value": 55, - "source": { - "type": "Property", - "value": "Speedometer" - }, - "instanceId": "urn:ngsi-ld:instance:31451425367", - "observedAt": "2022-08-09T18:25:02Z" - }, - { - "value": 56, - "source": { - "type": "Property", - "value": "Speedometer" - }, - "instanceId": "urn:ngsi-ld:instance:23856477893", - "observedAt": "2022-08-09T18:26:02Z" - } - ], + "value": 55, + "source": { + "type": "Property", + "value": "Speedometer" + }, + "instanceId": "urn:ngsi-ld:instance:31451425367", + "observedAt": "2022-08-09T18:25:02Z", "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" }, { "type": "Property", - "values": [ - { - "value": 54.5, - "source": { - "type": "Property", - "value": "GPS" - }, - "instanceId": "urn:ngsi-ld:instance:456234894533", - "observedAt": "2022-08-09T18:30:02Z" - }, - { - "value": 54.5, - "source": { - "type": "Property", - "value": "GPS" - }, - "instanceId": "urn:ngsi-ld:instance:720930032567", - "observedAt": "2022-08-09T18:33:02Z" - } - ], + "value": 56, + "source": { + "type": "Property", + "value": "Speedometer" + }, + "instanceId": "urn:ngsi-ld:instance:23856477893", + "observedAt": "2022-08-09T18:26:02Z", + "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" + }, + { + "type": "Property", + "value": 54.5, + "source": { + "type": "Property", + "value": "GPS" + }, + "instanceId": "urn:ngsi-ld:instance:456234894533", + "observedAt": "2022-08-09T18:30:02Z", + "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" + }, + { + "type": "Property", + "value": 54.5, + "source": { + "type": "Property", + "value": "GPS" + }, + "instanceId": "urn:ngsi-ld:instance:720930032567", + "observedAt": "2022-08-09T18:33:02Z", "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" } ], @@ -1327,7 +1323,7 @@ one. } ``` -#### C.2.3.2 Concise represenatation +#### C.2.3.2 Concise representation The concise representation is a terser, lossless form of the normalized representation, where redundant Attribute _`type`_ members are omitted and the diff --git a/md/clause-5.md b/md/clause-5.md index c3df0a831f7d289e069a5482084640339cac507b..f69d0904fa4bae4af8115f9200158cb774deede6 100644 --- a/md/clause-5.md +++ b/md/clause-5.md @@ -806,8 +806,8 @@ Core _`@context`_: - ["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 Property-scoped and used - by the Aggregated temporal representation of an Entity. See Clause 5.3.2.7 + ["sumsq"]{.HTML-Code}, ["totalCount"]{.HTML-Code} are used by the Aggregated + temporal representation of an Entity. See Clause 5.3.2.7 - ["bbox"]{.HTML-Code}, ["properties"]{.HTML-Code}, ["coordinates"]{.HTML-Code} are used in geographic operations and retain their standard GeoJSON-LD @@ -1099,7 +1099,7 @@ Table: NGSI-LD Property data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -1242,7 +1242,7 @@ Table: NGSI-LD Relationship data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -1439,7 +1439,7 @@ Table: NGSI-LD GeoProperty data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -1582,7 +1582,7 @@ Table: NGSI-LD LanguageProperty data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -1723,7 +1723,7 @@ Table: NGSI-LD VocabProperty data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -1853,7 +1853,7 @@ Table: NGSI-LD ListProperty data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -1986,7 +1986,7 @@ Table: NGSI-LD ListRelationship data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -2127,7 +2127,7 @@ Table: NGSI-LD JsonProperty data type definition +----------------------------------+-------------------------------------------------------+------------------------------------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ | >>> [!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. | +| In the simplified 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. | | | | >>> | | | @@ -3834,7 +3834,7 @@ 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). +operation (for an example see Annex C, Clause+++annex-c+++C.11). 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 @@ -4997,18 +4997,18 @@ the _`modifiedAt`_ sub-Property. 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. +_Attribute_ 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 +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. +Systems should maintain an _`instanceId`_ for each such _Attribute_ 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. @@ -5017,40 +5017,62 @@ allow modification or deletion, similar problems may be encountered. **Mandatory** -For Each _Attribute_, one of the following members shall be present: +Within the Array of JSON-LD objects holding each instance of an _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 +- ["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: +Aligning with the data type described above, on each instance of an _Attribute_, +the following member is also mandatory: - ["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} + ["ListRelationship"]{.HTML-Code}, ["JsonProperty"]{.HTML-Code} + + + +>>> [!tip] + +```json +"speed": [ + { + "type": "Property", + "value": 120, + "unitCode": "KMH", + "observedAt": "2018-08-01T12:03:00Z", + "instanceId": "urn:ngsi-ld:instance:14141732", + }, + { + "type": "Property", + "value": 80, + "unitCode": "KMH", + "observedAt": "2018-08-01T12:05:00Z", + "instanceId": "urn:ngsi-ld:instance:2236646", + } +] +``` + +>>> + + **Multi-Attribute Representation** @@ -5082,6 +5104,9 @@ containing the following members: - ["@context"]{.HTML-Code}, a JSON-LD _`context`_ as described in Clause+++root.3.2.1. + +For Each _Attribute_, one of the following members shall be present: + - 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 @@ -5425,7 +5450,7 @@ 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. +request parameters. The aggregation function is applied according to the following principles: @@ -5470,9 +5495,6 @@ The aggregated temporal representation of an Entity shall include the following: 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: @@ -5621,12 +5643,34 @@ Table: Semantics of aggregation methods for Relationships + + +>>> [!tip] + +```json +"speed": { + "type": "Property", + "max": [ + [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], + [100, "2018-08-01T12:04:00Z", "2018-08-01T12:08:00Z"] + ], + "avg": [ + [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], + [90, "2018-08-01T12:04:00Z", "2018-08-01T12:08:00Z"] + ] +} +``` + +>>> + + + **Multi-Attribute Representation** In the multi-attribute case (see Clause+++clause-8+++8.5), the aggregated values of a multi-Attribute are held as an array of JSON-LD objects separated by `datasetId`. An example of this representation can be found in Annex C, -Clause+++annex-c+++C.2.2.5 +Clause+++annex-c+++C.2.2.4.5 ### 5.3.3 GeoJSON