From 17eec087f6a591a2d8fa11ff5b69931b251f55d7 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 24 Oct 2025 18:06:37 +0200 Subject: [PATCH 1/2] Add multi-attribute examples. --- md/annex-c.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++- md/clause-5.md | 45 ++++++++++++-- 2 files changed, 197 insertions(+), 5 deletions(-) diff --git a/md/annex-c.md b/md/annex-c.md index 46b56cb..aa2c594 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,159 @@ 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 _`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", + "values": [ + { + "value": 55, + "source": { + "type": "Property", + "value": "Speedometer" + }, + "observedAt": "2022-08-09T18:25:02Z" + }, + { + "value": 56, + "source": { + "type": "Property", + "value": "Speedometer" + }, + "observedAt": "2022-08-09T18:26:02Z" + } + ], + "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" + }, + { + "type": "Property", + "values": [ + { + "value": 54.5, + "source": { + "type": "Property", + "value": "GPS" + }, + "observedAt": "2022-08-09T18:30:02Z" + }, + { + "value": 54.5, + "source": { + "type": "Property", + "value": "GPS" + }, + "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", + "values": { + "avg": 55.5, + "max": 56, + "min": 55, + "distinctCount": 2, + "totalCount": 2 + }, + "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" + }, + { + "type": "Property", + "values": { + "avg": 54.5, + "max": 54.5, + "min": 54.5, + "distinctCount": 1, + "totalCount": 2 + }, + "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 9fcd735..77926d0 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 -- GitLab From bfb0da341c025a072acd6f6bb9308cb77291318a Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 29 Oct 2025 18:15:50 +0100 Subject: [PATCH 2/2] - Add instanceIds - Amend Aggregated Example - Clarify Text --- md/annex-c.md | 55 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 17 deletions(-) diff --git a/md/annex-c.md b/md/annex-c.md index aa2c594..d9abd68 100644 --- a/md/annex-c.md +++ b/md/annex-c.md @@ -1106,9 +1106,10 @@ 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 _`datasetId`_ -enables individually creating, updating and deleting a particular instance -without affecting the instance from another source. +_`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 { @@ -1124,6 +1125,7 @@ without affecting the instance from another source. "type": "Property", "value": "Speedometer" }, + "instanceId": "urn:ngsi-ld:instance:31451425367", "observedAt": "2022-08-09T18:25:02Z" }, { @@ -1132,6 +1134,7 @@ without affecting the instance from another source. "type": "Property", "value": "Speedometer" }, + "instanceId": "urn:ngsi-ld:instance:23856477893", "observedAt": "2022-08-09T18:26:02Z" } ], @@ -1146,6 +1149,7 @@ without affecting the instance from another source. "type": "Property", "value": "GPS" }, + "instanceId": "urn:ngsi-ld:instance:456234894533", "observedAt": "2022-08-09T18:30:02Z" }, { @@ -1154,6 +1158,7 @@ without affecting the instance from another source. "type": "Property", "value": "GPS" }, + "instanceId": "urn:ngsi-ld:instance:720930032567", "observedAt": "2022-08-09T18:33:02Z" } ], @@ -1223,24 +1228,40 @@ individual attribute instances for speed; each is identified by a _`datasetId`_. "speed": [ { "type": "Property", - "values": { - "avg": 55.5, - "max": 56, - "min": 55, - "distinctCount": 2, - "totalCount": 2 - }, + "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", - "values": { - "avg": 54.5, - "max": 54.5, - "min": 54.5, - "distinctCount": 1, - "totalCount": 2 - }, + "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" } ], -- GitLab