Merge branch 'feature/value' into 'master'

#### 10.2.6.1 Description

This operation allows the modification of the value of an **already existing**

Attribute of an **existing** NGSI-LD Entity.

#### 10.2.6.2 Use case diagram

A [Context Producer]{.HTML-Keyboard} can set the value of an existing Attribute

within an NGSI-LD system as shown in Figure+++below.

<!-- prettier-ignore-start -->

::: FL

<img src="media/set-attribute-value-use-case.svg"/>

:::

::: TF

Figure: Set Attribute Value use case

:::

<!-- prettier-ignore-end -->

#### 10.2.6.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 to be modified, identified by a name.

- A JSON or JSON-LD document representing an NGSI-LD Attribute Fragment (see

  clause 5.4.2)

- An optional parameter indicating an _`observedAt`_ timestamp to use when

  setting the Attribute value.

- An optional parameter indicating a _`datasetId`_ to use when setting the

  Attribute value.

#### 10.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 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.

- If the request payload body is not a valid JSON document or the payload body

  contains ["urn:ngsi-ld:null"]{.HTML-Code} or contains [null]{.HTML-Code}

  (excepting for Attribute fragments representing a _JsonProperty_) then an

  error of type [InvalidRequest]{.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 payload body

  is forwarded for remote processing. For each matching registration:

  - If the Set Attribute Value operation is supported by the registration (see

    clause 9), matching input data is forwarded to the Registration endpoint.

  - If the Set Attribute Value operation is not supported by the registration,

    this shall result in an error of type [Conflict]{.HTML-Error} in case the

    complete set Attribute value failed, or in a partial success if some parts

    of the set Attribute value 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 set Attribute value 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}

- Replace the existing Attribute value instance with the value from the

  Attribute Fragment provided.

  - If the Attribute value to be replaced is represented in the **value only**

    representation, the _`type`_ of any pre-existing Attribute in the target

    entity shall be preserved.

  - Term to URI expansion within the Attribute Fragment shall be occur prior to

    Attribute value replacement (see clause 8.2.4)

  - If the Attribute whose value is to be set previously contained an

    _`observedAt`_ sub-Attribute and the value to be replaced is represented in

    the **value only** representation:

    - if an _`observedAt`_ timestamp is defined, then the _`observedAt`_

      sub-Attribute is updated using the timestamp supplied.

    - if no _`observedAt`_ timestamp is defined, then the _`observedAt`_

      sub-Attribute is removed.

#### 10.2.6.5 Output data

None.

### 10.2.7 Delete Attribute

#### 10.2.7.1 Description

#### 10.4.4.1 Description

This operation allows the retrieval of the value of an **already existing**

Attribute of an **existing** NGSI-LD Entity.

#### 10.4.4.2 Use case diagram

A [Context Producer]{.HTML-Keyboard} can retrieve the value of an existing

Attribute within an NGSI-LD system as shown in Figure+++below.

<!-- prettier-ignore-start -->

::: FL

<img src="media/retrieve-attribute-value-use-case.svg"/>

:::

::: TF

Figure: Retrieve Attribute Value use case

:::

<!-- prettier-ignore-end -->

#### 10.4.4.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).

- A flag indicating representation of the Attribute value to be returned

  (optional).

- Target Attribute whose value is to be retrieved, identified by a name.

- A specified language filter as per clause 7.2.7 (optional).

- A reference to a JSON-LD _`@context`_ (optional).

- A flag indicating whether to include additional inline [Linked

  Entities]{.HTML-Keyboard} corresponding to the _Relationship_ 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 instance is to be

  selected as defined by clause 8.5 (optional).

#### 10.4.4.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 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.

- For [Context Source Registrations]{.HTML-Keyboard} that match and support the

  retrieveAttribute 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.

- 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}

- The implementation shall retrieve the 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.

- When the _`datasetId`_ parameter is provided in the request:

  - Filter the Attribute instance based on the _`datasetId`_ parameter, i.e.

    keep only the Attribute instance 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}, 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.

#### 10.4.4.5 Output data

A JSON or JSON-LD document representing an NGSI-LD Attribute Fragment as

mandated by clause 5.4.2, formatted according to the defined representation,

where URI to Term compaction shall be applied according to the supplied

_`@context`_.

If a language filter is specified and the returned Attribute 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 the returned Attribute corresponds to an annotated

_Relationship_, then 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 the returned

Attribute 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 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.5 Context Information Subscription

### 10.5.1 Introduction

- 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_,

  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.

- 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

  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

## 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.

### 5.4.1 Element fragments

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.

When updating NGSI-LD Elements (Entities, TemporalEntities, [Context Source

Registrations]{.HTML-Keyboard}, Snapshots 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-LD Object which shall include the following

members:

An NGSI-LD Element 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 Element 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.

  (mutated) NGSI-LD element.

- ["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.

<!-- prettier-ignore-end -->

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.

When an Entity Fragment is received in the **concise format** (see

Clause+++root.3.2.3), it is first expanded into a normalized fragment before

being applied.

<!-- prettier-ignore-start -->

>>> [!tip] EXAMPLE 4:

The following NGSI-LD Fragment of an Entity in the **normalized format** allows the

modification the Entity by:

The following Entity Fragment in the **normalized format** allows the

modification of the Entity by:

- updating its _`locatedAt`_ _Relationship_ _`object`_

- updating its _`batteryLevel`_ _Property_ _`value`_

>>> [!tip] EXAMPLE 4:

The following NGSI-LD Fragment in the **concise format** allows the modification

The following Entity Fragment in the **concise format** allows the modification

of an Entity by:

- updating its _`locatedAt`_ _Relationship_ _`object`_

>>> [!tip] EXAMPLE 4:

The following NGSI-LD Fragment in the **normalized format** removes the

The following Entity Fragment in the **normalized format** removes the

_`exonym`_ _LanguageProperty_ from the Entity:

```json

>>> [!tip] EXAMPLE 5:

The following NGSI-LD Fragment in the **concise format** removes the _`exonym`_

The following Entity Fragment in the **concise format** removes the _`exonym`_

_LanguageProperty_ from the Entity:

```json

>>>

<!-- prettier-ignore-end -->

### 5.4.2 Attribute fragments

It is necessary to have a means of describing the value held within an

individual NGSI-LD Attribute. This is used when updating or retrieving the value

directly. In these cases, it shall be assumed that Entity ["id"]{.HTML-Code},

Entity ["type"]{.HTML-Code} and Attribute name can all be determined from the

operation signature.

The value _`null`_ shall not appear within Attribute fragments, with a limited

exception for Attribute fragments representing a _JsonProperty_, such as

[{"json": null}]{.HTML-Code}

A representation of NGSI-LD Null is only allowed within an Attribute fragment

during Partial update patch operations as described in clause 8.4.2

An Attribute 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 - i.e. ["type"]{.HTML-Code} and one of ["value"]{.HTML-Code},

["object"]{.HTML-Code}, ["languageMap"]{.HTML-Code}, ["vocab"]{.HTML-Code},

["valueList"]{.HTML-Code}, ["objectList"]{.HTML-Code} or ["json"]{.HTML-Code}.

Further members (such as ["datasetId"]{.HTML-Code}, ["observedAt"]{.HTML-Code})

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 Attribute 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 -->

An Attribute Fragment in the concise format, shall be a JSON Object compacted

according to the Normalized-to-Concise Compaction algorithm found in clause

5.3.2.2. However where present, the ["value"]{.HTML-Code} element shall not

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

Attribute Fragment

<!-- prettier-ignore-start -->

>>> [!tip] EXAMPLE 2:

Representation of an NGSI-LD Attribute 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 -->

An Attribute 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 -->

>>> [!tip] EXAMPLE 3:

Representation of an NGSI-LD Attribute Fragment of a _Property_ in the

**simplified format**:

```json

{

  "value": "Berlin",

  "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"

}

```

>>>

<!-- prettier-ignore-end -->

Where a binding explicitly defines a request or response to be **value only**,

the representation of an NGSI-LD Attribute Fragment changes, and shall be

represented purely as the Attribute value itself (e.g. directly as a JSON

Primitive, a JSON Object or JSON Array as necessary) rather than as a JSON

object holding a series of key-value pairs as described above.

<!-- prettier-ignore-start -->

>>> [!tip] EXAMPLE 4:

Value only Representation of an NGSI-LD Attribute Fragment

```json

"Berlin"

```

>>>

<!-- prettier-ignore-end -->

An _`@context`_ cannot be embedded within the Attribute fragment when using the

**value only** representation, therefore in this case, whenever an _`@context`_

is required, it shall be supplied through the use of a [Link]{.HTML-Code} header

(see [n.8] Section 6.2).