Loading md/clause-10.md +6 −6 Original line number Original line Diff line number Diff line Loading @@ -472,14 +472,14 @@ Figure: Set Attribute Value use case - Replace the existing Attribute value instance with the Value Fragment - Replace the existing Attribute value instance with the Value Fragment provided. provided. - If a user _`@context`_ has been supplied, the Value Fragment shall undergo - If the Attribute value to be replaced is represented in the **value only** expansion prior to replacement (see clause 8.2.4) - If the Attribute value to be replaced is represented in a simplified representation, the _`type`_ of any pre-existing Attribute in the target representation, the _`type`_ of any pre-existing Attribute in the target entity shall be preserved. entity shall be preserved. - If a user _`@context`_ has been supplied, the Value Fragment shall undergo expansion prior to replacement (see clause 8.2.4) - If the Attribute whose value is to be set previously contained an - If the Attribute whose value is to be set previously contained an _`observedAt`_ sub-Attribute and no _`observedAt`_ element can be found _`observedAt`_ sub-Attribute and the value to be replaced is represented in within the Value fragment then: the **value only** representation: - if an _`observedAt`_ timestamp is defined, then the _`observedAt`_ - if an _`observedAt`_ timestamp is defined, then the _`observedAt`_ sub-Attribute is updated using the timestamp supplied. sub-Attribute is updated using the timestamp supplied. Loading Loading @@ -2317,7 +2317,7 @@ Figure: Retrieve Attribute Value use case #### 10.4.4.5 Output data #### 10.4.4.5 Output data A JSON or JSON-LD document representing an NGSI-LD Value Fragment as mandated by A JSON or JSON-LD document representing an NGSI-LD Value Fragment as mandated by clause 5.5. formatted according to the defined representation. clause 5.5, formatted according to the defined representation. if an _`@context`_ is supplied and the returned Attribute corresponds to a if an _`@context`_ is supplied and the returned Attribute corresponds to a [VocabProperty]{.HTML-Keyboard}, the returned value shall be compacted according [VocabProperty]{.HTML-Keyboard}, the returned value shall be compacted according Loading md/clause-5.md +84 −16 Original line number Original line Diff line number Diff line Loading @@ -5826,16 +5826,38 @@ _LanguageProperty_ from the Entity: ## 5.5 NGSI-LD Value fragments ## 5.5 NGSI-LD Value fragments When updating the value of an individual NGSI-LD Attribute, it is necessary to When updating or retrieving the value of an individual NGSI-LD Attribute, it is have a means of describing the value to be updated. necessary to have a means of describing the value to be updated. The value _`null`_ or an NGSI-LD Null are prohibited within NGSI-LD Value fragments. A Value Fragment in the normalised format, shall at a minimum be a JSON Object A Value Fragment in the normalised format, shall at a minimum be a JSON Object holding the mandatory elements of an Attribute as described in clause 5.3.2.2 - holding the mandatory elements of an Attribute as described in clause 5.3.2.2 - i.e. ["type"]{.HTML-Code} and one of ["value"]{.HTML-Code}, i.e. ["type"]{.HTML-Code} and one of ["value"]{.HTML-Code}, ["object"]{.HTML-Code}, ["languageMap"]{.HTML-Code}, ["vocab"]{.HTML-Code}, ["object"]{.HTML-Code}, ["languageMap"]{.HTML-Code}, ["vocab"]{.HTML-Code}, ["valueList"]{.HTML-Code}, ["objectList"]{.HTML-Code} or ["json"]{.HTML-Code}. ["valueList"]{.HTML-Code}, ["objectList"]{.HTML-Code} or ["json"]{.HTML-Code}. Further members where present, shall follow the data types described in clause Further members (such as ["datasetId"]{.HTML-Code}, ["observedAt"]{.HTML-Code}) 5.2.6.4.8 and an optional. ["@context"]{.HTML-Code} may also be present. where present, shall follow the data types described in clause 5.2.6.4.8. An optional ["@context"]{.HTML-Code} may also be present. <!-- prettier-ignore-start --> >>> [!tip] EXAMPLE 1: Representation of an NGSI-LD Value Fragment of a _Property_ in the **normalised format**: ```json { "value": "Berlin", "type": "Property", "observedAt": "2022-03-14T12:51:02.000Z", "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" } ``` >>> <!-- prettier-ignore-end --> A Value Fragment in the concise format, shall be a JSON Object compacted A Value Fragment in the concise format, shall be a JSON Object compacted according to the Normalized-to-Concise Compaction algorithm found in clause according to the Normalized-to-Concise Compaction algorithm found in clause Loading @@ -5843,25 +5865,71 @@ according to the Normalized-to-Concise Compaction algorithm found in clause undergo full compaction if the property value is a JSON primitive or GeoJSON undergo full compaction if the property value is a JSON primitive or GeoJSON object, so that the ["value"]{.HTML-Code} element shall remain within the Fragment object, so that the ["value"]{.HTML-Code} element shall remain within the Fragment A Value Fragment in the simplified format, shall consist of a JSON <!-- prettier-ignore-start --> representation of Attribute value alone. the value _`null`_ or an NGSI-LD Null are prohibited. >>> [!tip] EXAMPLE 2: Representation of an NGSI-LD Value Fragment of a _Property_ in the **concise format**: ```json { "value": "Berlin", "observedAt": "2022-03-14T12:51:02.000Z", "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" } ``` >>> <!-- prettier-ignore-end --> A Value Fragment in the simplified format, shall consist of a JSON Object holding a representation of the Attribute value alone, and following the compaction rules of the concise representation described above. An ["@context"]{.HTML-Code}, and in the Multi-attribute case ["datasetId"]{.HTML-Code} may also be present. <!-- prettier-ignore-start --> <!-- prettier-ignore-start --> >>> [!note] NOTE: >>> [!tip] EXAMPLE 3: When an optional user _`@context`_ is supplied using a mechanism appropriate to the binding used, Value Fragments represented in the normalised and concise formats are valid JSON-LD documents. Value Fragments represented in the simplified format are valid JSON documents. Representation of an NGSI-LD Value Fragment of a _Property_ in the Use of a supplied user _`@context`_ is implied. **simplified format**: ```json { "value": "Berlin", "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" } ``` >>> >>> <!-- prettier-ignore-end --> <!-- prettier-ignore-end --> When updating the value of an individual NGSI-LD Attribute, it shall be assumed When updating or retrieving the value of an individual NGSI-LD Attribute, it shall that Entity [id"]{.HTML-Code}, Entity ["type"]{.HTML-Code} and Attribute name be assumed that Entity [id"]{.HTML-Code}, Entity ["type"]{.HTML-Code} and Attribute can all be determined from the operation signature. name can all be determined from the operation signature. Where the binding explicitly defines a request or response to be **value only**, the NGSI-LD Value Fragment shall be represented purely as a value (e.g. a JSON Primitive) rather than as a JSON Object. <!-- prettier-ignore-start --> >>> [!tip] EXAMPLE 4: Value only Representation of an NGSI-LD Value Fragment ```json "Berlin" ``` >>> <!-- prettier-ignore-end --> Loading
md/clause-10.md +6 −6 Original line number Original line Diff line number Diff line Loading @@ -472,14 +472,14 @@ Figure: Set Attribute Value use case - Replace the existing Attribute value instance with the Value Fragment - Replace the existing Attribute value instance with the Value Fragment provided. provided. - If a user _`@context`_ has been supplied, the Value Fragment shall undergo - If the Attribute value to be replaced is represented in the **value only** expansion prior to replacement (see clause 8.2.4) - If the Attribute value to be replaced is represented in a simplified representation, the _`type`_ of any pre-existing Attribute in the target representation, the _`type`_ of any pre-existing Attribute in the target entity shall be preserved. entity shall be preserved. - If a user _`@context`_ has been supplied, the Value Fragment shall undergo expansion prior to replacement (see clause 8.2.4) - If the Attribute whose value is to be set previously contained an - If the Attribute whose value is to be set previously contained an _`observedAt`_ sub-Attribute and no _`observedAt`_ element can be found _`observedAt`_ sub-Attribute and the value to be replaced is represented in within the Value fragment then: the **value only** representation: - if an _`observedAt`_ timestamp is defined, then the _`observedAt`_ - if an _`observedAt`_ timestamp is defined, then the _`observedAt`_ sub-Attribute is updated using the timestamp supplied. sub-Attribute is updated using the timestamp supplied. Loading Loading @@ -2317,7 +2317,7 @@ Figure: Retrieve Attribute Value use case #### 10.4.4.5 Output data #### 10.4.4.5 Output data A JSON or JSON-LD document representing an NGSI-LD Value Fragment as mandated by A JSON or JSON-LD document representing an NGSI-LD Value Fragment as mandated by clause 5.5. formatted according to the defined representation. clause 5.5, formatted according to the defined representation. if an _`@context`_ is supplied and the returned Attribute corresponds to a if an _`@context`_ is supplied and the returned Attribute corresponds to a [VocabProperty]{.HTML-Keyboard}, the returned value shall be compacted according [VocabProperty]{.HTML-Keyboard}, the returned value shall be compacted according Loading
md/clause-5.md +84 −16 Original line number Original line Diff line number Diff line Loading @@ -5826,16 +5826,38 @@ _LanguageProperty_ from the Entity: ## 5.5 NGSI-LD Value fragments ## 5.5 NGSI-LD Value fragments When updating the value of an individual NGSI-LD Attribute, it is necessary to When updating or retrieving the value of an individual NGSI-LD Attribute, it is have a means of describing the value to be updated. necessary to have a means of describing the value to be updated. The value _`null`_ or an NGSI-LD Null are prohibited within NGSI-LD Value fragments. A Value Fragment in the normalised format, shall at a minimum be a JSON Object A Value Fragment in the normalised format, shall at a minimum be a JSON Object holding the mandatory elements of an Attribute as described in clause 5.3.2.2 - holding the mandatory elements of an Attribute as described in clause 5.3.2.2 - i.e. ["type"]{.HTML-Code} and one of ["value"]{.HTML-Code}, i.e. ["type"]{.HTML-Code} and one of ["value"]{.HTML-Code}, ["object"]{.HTML-Code}, ["languageMap"]{.HTML-Code}, ["vocab"]{.HTML-Code}, ["object"]{.HTML-Code}, ["languageMap"]{.HTML-Code}, ["vocab"]{.HTML-Code}, ["valueList"]{.HTML-Code}, ["objectList"]{.HTML-Code} or ["json"]{.HTML-Code}. ["valueList"]{.HTML-Code}, ["objectList"]{.HTML-Code} or ["json"]{.HTML-Code}. Further members where present, shall follow the data types described in clause Further members (such as ["datasetId"]{.HTML-Code}, ["observedAt"]{.HTML-Code}) 5.2.6.4.8 and an optional. ["@context"]{.HTML-Code} may also be present. where present, shall follow the data types described in clause 5.2.6.4.8. An optional ["@context"]{.HTML-Code} may also be present. <!-- prettier-ignore-start --> >>> [!tip] EXAMPLE 1: Representation of an NGSI-LD Value Fragment of a _Property_ in the **normalised format**: ```json { "value": "Berlin", "type": "Property", "observedAt": "2022-03-14T12:51:02.000Z", "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" } ``` >>> <!-- prettier-ignore-end --> A Value Fragment in the concise format, shall be a JSON Object compacted A Value Fragment in the concise format, shall be a JSON Object compacted according to the Normalized-to-Concise Compaction algorithm found in clause according to the Normalized-to-Concise Compaction algorithm found in clause Loading @@ -5843,25 +5865,71 @@ according to the Normalized-to-Concise Compaction algorithm found in clause undergo full compaction if the property value is a JSON primitive or GeoJSON undergo full compaction if the property value is a JSON primitive or GeoJSON object, so that the ["value"]{.HTML-Code} element shall remain within the Fragment object, so that the ["value"]{.HTML-Code} element shall remain within the Fragment A Value Fragment in the simplified format, shall consist of a JSON <!-- prettier-ignore-start --> representation of Attribute value alone. the value _`null`_ or an NGSI-LD Null are prohibited. >>> [!tip] EXAMPLE 2: Representation of an NGSI-LD Value Fragment of a _Property_ in the **concise format**: ```json { "value": "Berlin", "observedAt": "2022-03-14T12:51:02.000Z", "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" } ``` >>> <!-- prettier-ignore-end --> A Value Fragment in the simplified format, shall consist of a JSON Object holding a representation of the Attribute value alone, and following the compaction rules of the concise representation described above. An ["@context"]{.HTML-Code}, and in the Multi-attribute case ["datasetId"]{.HTML-Code} may also be present. <!-- prettier-ignore-start --> <!-- prettier-ignore-start --> >>> [!note] NOTE: >>> [!tip] EXAMPLE 3: When an optional user _`@context`_ is supplied using a mechanism appropriate to the binding used, Value Fragments represented in the normalised and concise formats are valid JSON-LD documents. Value Fragments represented in the simplified format are valid JSON documents. Representation of an NGSI-LD Value Fragment of a _Property_ in the Use of a supplied user _`@context`_ is implied. **simplified format**: ```json { "value": "Berlin", "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" } ``` >>> >>> <!-- prettier-ignore-end --> <!-- prettier-ignore-end --> When updating the value of an individual NGSI-LD Attribute, it shall be assumed When updating or retrieving the value of an individual NGSI-LD Attribute, it shall that Entity [id"]{.HTML-Code}, Entity ["type"]{.HTML-Code} and Attribute name be assumed that Entity [id"]{.HTML-Code}, Entity ["type"]{.HTML-Code} and Attribute can all be determined from the operation signature. name can all be determined from the operation signature. Where the binding explicitly defines a request or response to be **value only**, the NGSI-LD Value Fragment shall be represented purely as a value (e.g. a JSON Primitive) rather than as a JSON Object. <!-- prettier-ignore-start --> >>> [!tip] EXAMPLE 4: Value only Representation of an NGSI-LD Value Fragment ```json "Berlin" ``` >>> <!-- prettier-ignore-end -->
