Commit e85a088f authored by Giuseppe Tropea's avatar Giuseppe Tropea
Browse files

Merge branch 'feature/value' into 'master'

DATA(25)000145_NGSI-LD_Core_Value_Endpoints

See merge request !8
parents 09a0df74 441a48c5
Loading
Loading
Loading
Loading
+240 −0
Original line number Diff line number Diff line
@@ -422,14 +422,101 @@ None.

#### 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
@@ -2172,14 +2259,167 @@ the operation shall be returned in a specific field in the response.

#### 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 ["&#64;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=&lt;&#8203;version&gt;"]{.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=&lt;&#8203;conformant-version&gt;"]{.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
+1 −1
Original line number Diff line number Diff line
@@ -158,7 +158,7 @@ Figure: Update context source registration use case
- 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.
+1 −1
Original line number Diff line number Diff line
@@ -236,7 +236,7 @@ Figure: Update Snapshot Status use case
- 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
+139 −17
Original line number Diff line number Diff line
@@ -5638,20 +5638,22 @@ An example can be found in Annex C, Clause+++annex-c+++C.2.3.
## 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.
@@ -5682,9 +5684,9 @@ changing its endpoint's URI:
<!-- 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 -->
@@ -5741,8 +5743,8 @@ _`address`_ Property. i.e a modification of a Property of a Property.
>>> [!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`_
@@ -5779,7 +5781,7 @@ modification the Entity by:
>>> [!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`_
@@ -5817,7 +5819,7 @@ Clause+++clause-8+++8.4.3) shall be encoded as the JSON object [{"&#64;none":
>>> [!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
@@ -5845,7 +5847,7 @@ format**.
>>> [!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
@@ -5859,3 +5861,123 @@ _LanguageProperty_ from the Entity:
>>>
<!-- 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).
+4 −0

File added.

Preview size limit exceeded, changes collapsed.

Loading