diff --git a/md/annex-c.md b/md/annex-c.md index 46b56cb6ab31d0b9a19528b9c5aff9856a6576f8..d9abd68959c06b3fec2fd11ef26b2d3be49a313a 100644 --- a/md/annex-c.md +++ b/md/annex-c.md @@ -1036,7 +1036,7 @@ 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 +instance from another source. ```json { @@ -1050,6 +1050,7 @@ instance from another source "type": "Property", "value": "Speedometer" }, + "observedAt": "2022-08-09T18:25:02Z", "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" }, { @@ -1059,6 +1060,7 @@ instance from another source "type": "Property", "value": "GPS" }, + "observedAt": "2022-08-09T18:30:02Z", "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" } ], @@ -1099,6 +1101,180 @@ level of the graph only. } ``` +##### C.2.2.4.3 Normalized Temporal multi-Attribute example + +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 an +Attribute's _`datasetId`_ and the _`instanceId`_ associated to each value enables +modification of a particular instance value without affecting instances from other +sources. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "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" + } + ], + "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" + } + ], + "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.4 Simplified Temporal multi-Attribute example + +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`_. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "values": [ + [55, "2022-08-09T18:25:02Z"], + [56, "2022-08-09T18:26:02Z"] + ], + "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" + }, + { + "type": "Property", + "values": [ + [54.5, "2022-08-09T18:30:02Z"], + [54.5, "2022-08-09T18:33:02Z"] + ], + "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" + } + ], + "@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.2.4.5 Aggregated Temporal multi-Attribute example + +Below is an example, where aggregation 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`_. + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "avg": [ + [55.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "max": [ + [56, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "min": [ + [55, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "distinctCount": [ + [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "totalCount": [ + [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" + }, + { + "type": "Property", + "avg": [ + [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "max": [ + [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "min": [ + [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "distinctCount": [ + [1, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "totalCount": [ + [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" + } + ], + "@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 diff --git a/md/clause-5.md b/md/clause-5.md index 9fcd735827ea8ff97db34d3833407c0050e68443..77926d0219d661a673bd1403fc849e7267d5b98c 100644 --- a/md/clause-5.md +++ b/md/clause-5.md @@ -109,6 +109,7 @@ is more commonly used _._ - **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 @@ -3824,7 +3825,8 @@ Link header (see Clause+++clause-6+++6.2.4). 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. +computational description of this process in terms of an algorithm. An example +of this representation can be found in Annex C, Clause+++annex-c+++C.2.2.1. The JSON-LD object that contains the following members: @@ -3921,6 +3923,13 @@ 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. +**Multi-Attribute Representation** + +In the multi-attribute case (see Clause+++clause-8+++8.5), the 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.4.1 + #### 5.3.2.3 Entities Concise _Attributes_, their values and their sub-attributes can be represented in two @@ -3933,7 +3942,7 @@ 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 +Clause+++annex-c+++C.2.2.2 **Normalized-to-Concise Compaction** @@ -3953,6 +3962,7 @@ For Each _Attribute_: 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. @@ -3967,6 +3977,7 @@ For Each _Attribute_: ["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. @@ -4283,7 +4294,8 @@ 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 +example of this representation can be found in Annex C, +Clause+++annex-c+++C.2.2.3 The representation of an Entity in the **simplified format** shall be a JSON-LD object containing the following members: @@ -4475,7 +4487,8 @@ For Each Attribute : **Multi-Attribute Representation** In the multi-attribute case (see Clause+++clause-8+++8.5), the simplified format -of Attributes changes. +of Attributes changes. An example of this representation can be found in Annex +C, Clause+++annex-c+++C.2.2.4.2 For Each Attribute : @@ -4889,6 +4902,13 @@ data type described above: ["VocabProperty"]{.HTML-Code}, ["ListProperty"]{.HTML-Code}, ["Relationship"]{.HTML-Code}, ["JsonProperty"]{.HTML-Code} +**Multi-Attribute Representation** + +In the multi-attribute case (see Clause+++clause-8+++8.5), the temporal 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.4.3 + #### 5.3.2.6 Temporal Simplified The NGSI-LD specification defines an alternative, abbreviated temporal @@ -5240,6 +5260,13 @@ containing the following members: +**Multi-Attribute Representation** + +In the multi-attribute case (see Clause+++clause-8+++8.5), the temporal 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.4.4 + #### 5.3.2.7 Temporal Aggregated The NGSI-LD specification defines an alternative temporal representation of @@ -5262,6 +5289,7 @@ The aggregation function is applied according to the following principles: 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 @@ -5272,6 +5300,7 @@ The aggregated temporal representation of an Entity shall include the following: 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_ @@ -5442,6 +5471,13 @@ Table: Semantics of aggregation methods for Relationships +**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 + ### 5.3.3 GeoJSON #### 5.3.3.1 Introduction @@ -5485,6 +5521,7 @@ members: 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