Retrieve Attribute

#### 10.2.6.1 Description

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

Attribute of an existing NGSI-LD Entity.

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

#### 10.2.6.2 Use case diagram

  5.5)

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

  setting the Attribute value.

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

  Attribute value.

#### 10.2.6.4 Behaviour

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

  contains [null]{.HTML-Code} or ["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

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

  then an error of type [ResourceNotFound]{.HTML-Error}

- Replace the existing Attribute value instance with the Value Fragment

  provided.

  - If a user _`@context`_ has been supplied, the Value Fragment shall undergo

    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

    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.

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

    _`observedAt`_ sub-Attribute and no _`observedAt`_ element can be found

    within the Value fragment then:

    - 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 updated using the timestamp of the [Context

      Broker]{.HTML-Keyboard}

#### 10.2.6.5 Output data

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

  - 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

    specified.

#### 10.4.4.1 Description

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

Attribute of an existing NGSI-LD Entity.

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

#### 10.4.4.2 Use case diagram

#### 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 (Property or Relationship) 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 Value Fragment.

A JSON or JSON-LD document representing an NGSI-LD Value Fragment as mandated by

clause 5.5. formatted according to the defined representation.

if an _`@context`_ is supplied and the returned Attribute corresponds to a

[VocabProperty]{.HTML-Keyboard}, the returned value shall be compacted according

to 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

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 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 where present, shall follow the data types described in clause

5.2.6.4.8 and an optional. ["@context"]{.HTML-Code} may also be present.

A Value 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 Fragment

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

representation of Attribute value alone.

representation of Attribute value alone. the value _`null`_ or an NGSI-LD Null

are prohibited.

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

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.