Add Set Attribute Value

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

<image src="media/imageXXX.png"/>

:::

::: 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 (Property or Relationship) to be modified, identified by a

  name.

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

  5.5)

- An optional parameter indicating an _`observedAt`_ timestamp 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

  is ["urn:ngsi-ld:null"]{.HTML-Code}, 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 Aet 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 Fragment

  provided.

  - If the Attribute value to be replaced is represented in a simplified

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

    entity shall be preserved.

  - If a user _`@context`_ has been supplied, and the Attribute to be replaced is

    a VocabProperty, the Attribute's value shall undergo expansion prior to

    replacement (see clause 8.2.4)

  - If an _`observedAt`_ timestamp is defined and the Attribute value to be set

    previously contained an _`observedAt`_ sub-Attribute, the _`observedAt`_

    sub-Attribute is also updated using the timestamp.

#### 10.2.6.5 Output data

None.

### 10.2.7 Delete Attribute

#### 10.2.7.1 Description

- If an **exclusive** or **redirect** [Context Source

  Registration]{.HTML-Keyboard} matches against the input data, the input data

  (see clause 9.4), the input data is forwarded. For each matching registration:

  - If the Delete Attribute operation is supported by the registration (see

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

  - If the Delete Attribute update operation is not supported by the matched

- If an **exclusive** or **redirect** [Context Source

  Registration]{.HTML-Keyboard} matches against the id, the request is forwarded

  for remote processing. For each matching registration:

  - If the Delete Entity operation is supported by the registration (see clause

    9), the request is forwarded to the Registration endpoint.

  - If the Delete Entity update operation is not supported by the matched

- If an **exclusive** or **redirect** [Context Source

  Registration]{.HTML-Keyboard} matches against the input data, Attributes from

  matching input data are forwarded. For each matching registration:

  - If the Merge Entity operation is supported by the matched registration (see

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

  - If the Merge Entity operation is not supported by the matched registration,

- Then, implementations shall perform a merge operation over the target Entity

  as mandated by clause 8.4.3, using the following procedure:

- For each Attribute (Property or Relationship) included by the Entity Fragment:

  - If the target Entity does not include a matching Attribute (considering term

    expansion rules as mandated by clause 8.2.4), then such Attribute shall be

    appended to the target Entity.

  - If the target Entity already includes a matching Attribute (considering term

    expansion rules as mandated by clause 8.2.4):

    - If the Attribute (Property or Relationship) to be merged is represented in

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

      the target entity shall be preserved.

      the _`observedAt`_ sub-Attribute.

    - If a _`datasetId`_ is present in the Attribute included by the Entity

      Fragment:

      - If an Attribute instance in the target Entity has the same*`datasetId`*

        - If overwrite is allowed and the Attribute value is not NGSI-LD Null,

          then the existing Attribute with the specified*`datasetId`*

        - If overwrite is allowed and the Attribute value is NGSI-LD Null, then

    - If no _`datasetId`_ is present in the Attribute included by the Entity

      Fragment, the default Attribute instance is targeted:

      - If the default Attribute instance is present:

        - If overwrite is allowed and the Attribute value is not NGSI-LD Null,

          then the existing Attribute in the target Entity shall be merged with

          the new one supplied.

- If an **exclusive** or **redirect** [Context Source

  Registration]{.HTML-Keyboard} matches against the input data, Attributes from

  matching input data are forwarded. For each matching registration:

  - If the Replace Entity operation is supported by the registration (see clause

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

  - If the Replace Entity operation is not supported by the registration, this

- If an **exclusive** or **redirect** [Context Source

  Registration]{.HTML-Keyboard} matches against the input data, the input data

  is forwarded. For each matching registration:

  - If the Replace Attribute operation is supported by the registration (see

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

  - If the Replace Attribute operation is not supported by the registration,

  mandated by clause 7.2.5, for an example see annex C, clause C.5.15).

- And thereafter:

  - when no restrictive list of Entity member names is present, the

    implementation shall delete all Entities that can be found locally using

    retrieved list of Entity ids;

  array.

- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context

  Registry]{.HTML-Keyboard}:

  - Let IN be a copy of the original input array.

  - Remove from IN all Entities not matched by CSR and remove non-matching

    Attributes from the remaining Entities.

  - If IN is empty, continue with the next [Context Source

    Registration]{.HTML-Keyboard} if there is any.

  - If the Batch Entity Creation operation is supported by CSR:

    - Forward the Batch Entity Creation request with IN as input Array.

    - Merge the returned list of Entities successfully created with S.

    - Merge the returned list of Entities in Error with E.

  - Otherwise, if the Create Entity operation (clause 10.2.2) is supported by

    CSR:

    - For each Entity EN in the input array:

      - Forward a Create Entity request for Entity EN.

      - Merge any successful result(s) for Entity EN created with S.

  array.

- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context

  Registry]{.HTML-Keyboard}:

  - Let IN be a copy of the original input array.

  - Remove from IN all Entities not matched by CSR and remove non-matching

    Attributes from the remaining Entities.

    Registration]{.HTML-Keyboard} if there is any.

  - If the Batch Entity Creation or Update (Upsert) operation is supported by

    CSR:

    - Forward the Batch Entity Creation or Update (Upsert) request with IN as

      input Array.

    - Merge the returned list of Entities successfully created with S.

  - Otherwise, if the Create Entity operation (clause 10.2.2) is supported by

    CSR:

    - For each Entity EN in the input array:

      - Forward a Create Entity request for Entity EN.

      - If an error of type[AlreadyExists]{.HTML-Error} is returned:

        - If the Replace Entity operation (clause 10.2.28) is supported by CSR

  - Otherwise, if the Replace Entity operation (clause 10.2.28) is supported by

    CSR and the value of the update mode flag is Replace or the flag is not set:

    - Forward a Replace Entity request for Entity EN.

    - Merge any successful result(s) for Entity EN updated with S.

    - Merge any error result(s) for Entity EN updated with E.

  - Otherwise, if the Update Attributes operation (clause 10.2.3) is supported

    by CSR and the value of the update mode flag is Update:

    - Forward an Update Attributes request for Entity EN.

    - Merge any successful result(s) for Entity EN updated with S.

    - Merge any error result(s) for Entity EN updated with E.

- For each of the NGSI-LD Entities included in the input Array implementations

  shall:

  - Create the Entity locally if it does not exist (i.e. no Entity with the same

    Entity ID is present) executing the behaviour defined by clause 10.2.2, but

    limited to a local operation. In case of multiple instances of the same

  array.

- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context

  Registry]{.HTML-Keyboard}:

  - Let IN be a copy of the original input array.

  - Remove from IN all Entities not matched by CSR and remove non-matching

    Attributes from the remaining Entities.

  - If IN is empty, continue with the next [Context Source

    Registration]{.HTML-Keyboard} if there is any.

  - If the Batch Entity Update operation is supported by CSR:

    - Forward the Batch Entity Update request with IN as input Array.

    - Merge the returned list of Entities successfully created with S.

    - Merge the returned list of Entities in Error with E.

  - Otherwise, if the Update Attributes operation (clause 10.2.3) is supported

    by CSR and Attribute overwrite is permitted:

    - For each Entity EN in the input array:

      - Forward an Update Attributes request for Entity EN.

      - Merge any successful result(s) for Entity EN updated with S.

  - Otherwise, if the Append Attributes operation (clause 10.2.4) is supported

    by CSR and Attribute overwrite is not permitted:

    - For each Entity EN in the input array:

      - Forward an Append Attributes request for Entity EN with Attribute

        overwrite disabled:

  array.

- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context

  Registry]{.HTML-Keyboard}:

  - Let IN be a copy of the original input array.

  - Remove from IN all Entities not matched by CSR and remove non-matching

    Attributes from the remaining Entities.

  - If IN is empty, continue with the next [Context Source

    Registration]{.HTML-Keyboard} if there is any.

  - If the Batch Entity Merge operation is supported by CSR:

    - Forward the Batch Entity Merge request with IN as input Array.

    - Merge the returned list of Entities successfully created with S.

    - Merge the returned list of Entities in Error with E.

  - Otherwise, if the Merge Entity operation (clause 10.2.27) is supported by

    CSR:

    - For each Entity EN in the input array:

      - Forward a Merge Entity request for Entity EN.

      - Merge any successful result(s) for Entity EN merged with S.

  array.

- For each [Context Source Registration]{.HTML-Keyboard} CSR in the [Context

  Registry]{.HTML-Keyboard}:

  - Let IN be a copy of the original input array.

  - Remove from IN all Entities not matched by CSR and remove non-matching

    Attributes from the remaining Entities.

  - If IN is empty, continue with the next [Context Source

    Registration]{.HTML-Keyboard} if there is any.

  - If the Batch Entity Delete operation is supported by CSR:

    - Forward the Batch Entity Delete request with IN as input Array.

    - Merge the returned list of Entities successfully created with S.

    - Merge the returned list of Entities in Error with E.

  - Otherwise, if the Delete Entity operation (clause 10.2.8) is supported by

    CSR:

    - For each Entity EN in the input array:

      - Forward a Delete Entity request for Entity EN.

      - Merge any successful result(s) for Entity EN deleted with S.

  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

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

  retrieveEntity 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

  clause 8.2.4.

- For each Attribute found in the target Entity, when the _`datasetId`_

  parameter is provided in the request:

  - Filter the Attribute instances based on the _`datasetId`_ arameter, i.e.

    keep only the Attribute instances whose _`datasetId`_ is specified. The

    default Attribute instance is matched, if ["@none"]{.HTML-Code} is

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

  is not specified, implementations shall run a query that shall return an

  Entity Array containing all the Entities found locally, that meet all of the

  following conditions (given the respective parameter is provided):

  - id is equal to any of the id(s) passed as a parameter;

  - the Entity Type names match the selector of Entity Types (expanded) that is

    passed as a parameter;

- Otherwise, implementations shall run a query that shall return an Entity Array

  containing all the Entities found locally, that meet **all** of the following

  conditions (given the respective parameter is provided):

  - id is equal to any of the id(s) passed as a parameter;

  - the Entity Type names match the selector of Entity Types (expanded) that is

    passed as a parameter;

- 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

  Registrations]{.HTML-Keyboard} that match the query and support the

  "queryEntity" 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 [Entity

  the default setting of the deployment allows split Entities, and local scope

  is not specified, the following filters shall be applied on the aggregated

  Entities:

  - the filter conditions specified by the query are met (as mandated by clause

    7.2.3);

  - the geospatial restrictions imposed by the geoquery are met (as mandated by

- For each Attribute found in the target Entity, when _`datasetId`_ parameter is

  provided in the request:

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

    keep only the Attribute instances whose _`datasetId`_ is specified. The

    default Attribute instance is matched, if ["@none"]{.HTML-Code} is

  ["application/ld+json",]{.HTML-Code} a JSON-LD array is returned, representing

  the Entities 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 elements of the JSON-LD array to conform to the

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

<image src="media/imageXXX.png"/>

:::

::: TF

Figure: Retrieve Attribute Value use case

:::

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

#### 10.4.4.3 Input data

#### 10.4.4.4 Behaviour

#### 10.4.4.5 Output data

- A JSON or JSON-LD document representing an NGSI-LD Attribute Value Fragment.

## 10.5 Context Information Subscription

### 10.5.1 Introduction

- Then, implementations shall add a new Subscription. The behaviour for

  corresponding notifications shall be as per clause 10.5.7. The parameters of

  the created Subscription shall be configured as follows:

  - The Subscription expiration date shall be equal to the value of the

    [expiresAt]{.HTML-Variable} member. If the expiration timestamp provided

    represents a moment before the current date and time, then an error of type

  Source]{.HTML-Keyboard} Notification with the [subscriptionId]{.HTML-Variable}

  of the previously created [Context Source Registration]{.HTML-Keyboard}

  Subscription is received, implementations shall do the following:

  - For any **exclusive**, **redirect** and **inclusive** [Context Source

    Registration]{.HTML-Keyboard} received as part of the notification,

    implementation shall do the following depending on the

  copied. If the [splitEntities]{.HTML-Variable} member of the local

  Subscription is explicitly set to true or, if not explicitly set, the default

  setting of the deployment allows split entities:

  - The Entities contained in the data member of the Notification shall be

    retrieved locally and from all Context Sources that have information about

    these Entities, except for the one from which the Notification has been

  the local Subscription, using this local Subscription identifier instead of

  the _`subscriptionId`_ **received**.

- A Notification shall be sent as follows:

  - The structure of the notification message shall be as mandated by clause

    5.2.6.9.1.

  - The _`@context`_ to be used is the one specified in the _`jsonldContext`_

  - If an Attribute has been deleted, only the name of the attribute as key and

    the URI ["urn:ngsi-ld:null"]{.HTML-Code} as value shall be provided, unless

    more information is required. The latter is the case, if:

    - a _`datasetId`_ needs to be provided;

    - the _`notification.sysAttrs`_ is set to _`true`_ and thus the system

      generated sub-attributes (see clause 5.2.4) have to be provided;

  representing the current date and time.

- If the response to the notification request is 200 OK then implementations

  shall:

  - Update _`notification.lastSuccess`_ with a timestamp representing the

    current date and time.

  - Update _`notification.status`_ to ["ok"]{.HTML-Code}.

>>>

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

## 5.5 NGSI-LD Value fragments

When updating the value of an individual NGSI-LD Attribute, it is necessary to

have a means of describing the value to be updated.

A Value Fragment in the normalised format, shall 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 ["type"]{.HTML-Code}. An optional

["@context"]{.HTML-Code} may also be present.

A Value Fragment in the concise format, shall be a JSON Object as described for

the normalised form, but the ["type"]{.HTML-Code} shall be omitted.

A Value Fragment in the simplified format, shall consist of a JSON

representation of Attribute value alone.

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

>>> [!note] NOTE:

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.

Use of a supplied user _`@context`_  is implied.

>>>

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

When updating the value of an individual NGSI-LD Attribute, it shall be assumed

that Entity [id"]{.HTML-Code}, Entity ["type"]{.HTML-Code} and Attribute name

can all be determined from the operation signature.