diff --git a/md/clause-10.md b/md/clause-10.md index f0c8bfc7386bcd28411707de1afb9b2c75267755..1201816db1c3550d4d59b94cdd80042ef9188aa8 100644 --- a/md/clause-10.md +++ b/md/clause-10.md @@ -395,14 +395,102 @@ 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. + + + +::: FL + +::: + +::: TF +Figure: Set Attribute Value use case +::: + + + #### 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. +- An optional parameter indicating an _`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 [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 + 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 the **value only** + representation, the _`type`_ of any pre-existing Attribute in the target + entity shall be preserved. + - If a user _`@context`_ has been supplied, the Value Fragment shall undergo + expansion prior to 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 updated using the timestamp of the [Context + Broker]{.HTML-Keyboard} + #### 10.2.6.5 Output data +None. + ### 10.2.7 Delete Attribute #### 10.2.7.1 Description @@ -448,6 +536,7 @@ Figure: Delete Attribute use case - 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 @@ -522,6 +611,7 @@ Figure: Delete Entity use case - 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 @@ -590,6 +680,7 @@ The following behaviour shall be exhibited by compliant implementations: - 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, @@ -612,11 +703,13 @@ The following behaviour shall be exhibited by compliant implementations: - 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. @@ -631,7 +724,9 @@ The following behaviour shall be exhibited by compliant implementations: 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 @@ -643,7 +738,9 @@ The following behaviour shall be exhibited by compliant implementations: - 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. @@ -713,6 +810,7 @@ Figure: Replace Entity use case - 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 @@ -783,6 +881,7 @@ Figure: Replace Attribute use case - 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, @@ -914,6 +1013,7 @@ If the execution of the operation is limited to the local scope (see clause 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; @@ -990,11 +1090,11 @@ within an NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Create a batch of Entities use case ::: @@ -1021,6 +1121,7 @@ Implementations shall exhibit the following behaviour: 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. @@ -1033,12 +1134,14 @@ Implementations shall exhibit the following behaviour: - 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. @@ -1085,11 +1188,11 @@ within an NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Upsert a batch of Entities use case ::: @@ -1129,6 +1232,7 @@ Implementations shall exhibit the following behaviour: 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. @@ -1142,6 +1246,7 @@ Implementations shall exhibit the following behaviour: 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. @@ -1149,7 +1254,9 @@ Implementations shall exhibit the following behaviour: - 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 @@ -1166,12 +1273,14 @@ Implementations shall exhibit the following behaviour: - 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. @@ -1183,6 +1292,7 @@ Implementations shall exhibit the following behaviour: - 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 @@ -1223,11 +1333,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Update a batch of Entities use case ::: @@ -1265,6 +1375,7 @@ Implementations shall exhibit the following behaviour: 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. @@ -1278,12 +1389,14 @@ Implementations shall exhibit the following behaviour: - 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. @@ -1291,6 +1404,7 @@ Implementations shall exhibit the following behaviour: - 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: @@ -1334,11 +1448,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Merge a batch of Entities use case ::: @@ -1371,6 +1485,7 @@ Implementations shall exhibit the following behaviour: 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. @@ -1384,12 +1499,14 @@ Implementations shall exhibit the following behaviour: - 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. @@ -1429,11 +1546,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Delete a batch of Entities use case ::: @@ -1459,6 +1576,7 @@ Implementations shall exhibit the following behaviour: 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. @@ -1472,12 +1590,14 @@ Implementations shall exhibit the following behaviour: - 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. @@ -1593,8 +1713,10 @@ Figure: Retrieve Entity use case 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 @@ -1608,6 +1730,7 @@ Figure: Retrieve Entity use case - 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 @@ -1631,7 +1754,8 @@ Figure: Retrieve Entity use case 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. + + - 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. @@ -1646,6 +1770,7 @@ Figure: Retrieve Entity use case ["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 @@ -1872,6 +1997,7 @@ If the execution of the operation is limited to the local scope (see clause 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; @@ -1880,6 +2006,7 @@ If the execution of the operation is limited to the local scope (see clause - 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; @@ -1899,8 +2026,10 @@ If the execution of the operation is limited to the local scope (see clause - 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 @@ -1915,6 +2044,7 @@ If the execution of the operation is limited to the local scope (see clause 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 @@ -1942,6 +2072,7 @@ If the execution of the operation is limited to the local scope (see clause 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 @@ -1962,6 +2093,7 @@ If the execution of the operation is limited to the local scope (see clause - 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 @@ -1973,6 +2105,7 @@ If the execution of the operation is limited to the local scope (see clause ["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 @@ -2051,14 +2184,170 @@ 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. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Attribute Value use case +::: + + + #### 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 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 ### 10.5.1 Introduction @@ -2110,6 +2399,7 @@ Figure: Create subscription use case - 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 @@ -2161,6 +2451,7 @@ Figure: Create subscription use case 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 @@ -2464,6 +2755,7 @@ in subscribed Entities. Implementations shall exhibit the following behaviour: 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 @@ -2478,6 +2770,7 @@ in subscribed Entities. Implementations shall exhibit the following behaviour: 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`_ @@ -2495,6 +2788,7 @@ in subscribed Entities. Implementations shall exhibit the following behaviour: - 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; @@ -2541,6 +2835,7 @@ in subscribed Entities. Implementations shall exhibit the following behaviour: 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}. diff --git a/md/clause-5.md b/md/clause-5.md index 9fcd735827ea8ff97db34d3833407c0050e68443..d80ad86f29f193ab6dc7f51f221f74deccd6c4b0 100644 --- a/md/clause-5.md +++ b/md/clause-5.md @@ -5823,3 +5823,119 @@ _LanguageProperty_ from the Entity: >>> + +## 5.5 NGSI-LD Value 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. + +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 (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. + + + +>>> [!tip] EXAMPLE 1: + +Representation of an NGSI-LD Value 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" +} +``` + +>>> + + + +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 + + + +>>> [!tip] EXAMPLE 2: + +Representation of an NGSI-LD Value 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" +} +``` + +>>> + + + +A Value 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. + + + +>>> [!tip] EXAMPLE 3: + + +Representation of an NGSI-LD Value 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" +} +``` + +>>> + + + +Where a binding explicitly defines a request or response to be **value only**, +the representation of an NGSI-LD Value 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. + + + +>>> [!tip] EXAMPLE 4: + +Value only Representation of an NGSI-LD Value Fragment + +```json +"Berlin" +``` + +>>> + + + +An _`@context`_ cannot be embedded within the NGSI-LD Value 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 header +(see Clause+++clause-6+++6.2.4). + +The value _`null`_ or any representation of NGSI-LD Null are prohibited within +NGSI-LD Value fragments.