Added in error

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

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

### 10.5.1 Introduction