From 6b14af7d0020ed170f7c7fd91318243acd9dfbd6 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 19 Nov 2025 15:38:49 +0100 Subject: [PATCH 1/8] Clarify Auxilliary Registrations Behaviour --- md/clause-9.md | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/md/clause-9.md b/md/clause-9.md index a7e2ce6..c46b561 100644 --- a/md/clause-9.md +++ b/md/clause-9.md @@ -37,11 +37,6 @@ kind of context data a [Context Broker]{.HTML-Keyboard} can exchange such as Entity IDs, entity types, attribute names, geofenced areas, etc. Ultimately, all constraints specified in the registration shall be respected. -When a [Context Source]{.HTML-Keyboard} is registered, an operation mode is -selected. This defines the basis for distributed operations and also defines -whether or not the [Context Broker]{.HTML-Keyboard} is permitted to hold context -data about the Entities and Attributes locally itself. - If two registered [Context Sources]{.HTML-Keyboard} are providing context data for the same Attribute, the Attribute instances can be distinguished by _`datasetId`_. The mechanism for determining which data shall be returned is @@ -275,6 +270,11 @@ defined as ["federationOps"]{.HTML-Code}. ### 9.3.1 Introduction +When a [Context Source]{.HTML-Keyboard} is registered, one of four modes of +operation is selected. This defines the basis for distributed operations and +also defines whether or not the [Context Broker]{.HTML-Keyboard} is permitted to +hold context data about the Entities and Attributes locally itself. + ### 9.3.2 Additive registrations For additive registrations, the [Context Broker]{.HTML-Keyboard} is permitted to @@ -347,6 +347,28 @@ conflict to the registration. In the case that multiple overlapping **redirect** registrations are defined, operations are distributed to all registered [Context Sources]{.HTML-Keyboard}. +### 9.3.4 Precidence of distributed operations + +The presence of a matching **exclusive** [Context Source +Registration]{.HTML-Keyboard} indicates that no further local or distributed +operations shall occur on the specified Attribute of a given Entity. Operations +associated with an **exclusive** [Context Source Registration]{.HTML-Keyboard} +are always processed before any other local or distributed operations. + +Distributed operations triggered by **inclusive** [Context Source +Registrations]{.HTML-Keyboard} can take place in parallel to local operations. +When retrieving Entities, the algorithm defined in clause 8.5.3 shall apply in +case of conflict. **redirect** operations are similar, but no actions shall take +place within the local [Context Broker]{.HTML-Keyboard}. + +**auxiliary** [Context Source Registrations]{.HTML-Keyboard} only apply during +context information consumption operations, and any distributed operation +asociated with an **auxiliary** [Context Source Registration]{.HTML-Keyboard} +shall only be triggered if no matching data has been received from all +previously encountered [Context Sources]{.HTML-Keyboard}, so that the +possibility of data retrieval from local and all other matching distributed +[Context Sources]{.HTML-Keyboard} has been exhausted. + ## 9.4 Matching Context Source registrations When querying [Context Source Registrations]{.HTML-Keyboard} as described in -- GitLab From ee36bdedfe50a73031e9d7d8321f109b64dd67a5 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Thu, 20 Nov 2025 12:09:26 +0100 Subject: [PATCH 2/8] Fix typo --- md/clause-9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/md/clause-9.md b/md/clause-9.md index c46b561..a07f01e 100644 --- a/md/clause-9.md +++ b/md/clause-9.md @@ -347,7 +347,7 @@ conflict to the registration. In the case that multiple overlapping **redirect** registrations are defined, operations are distributed to all registered [Context Sources]{.HTML-Keyboard}. -### 9.3.4 Precidence of distributed operations +### 9.3.4 Precedence of distributed operations The presence of a matching **exclusive** [Context Source Registration]{.HTML-Keyboard} indicates that no further local or distributed -- GitLab From bed47c93afcf61cca4866c6237a5a97230caef80 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Thu, 20 Nov 2025 12:19:31 +0100 Subject: [PATCH 3/8] triggered => applied. --- md/clause-9.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/md/clause-9.md b/md/clause-9.md index a07f01e..8bce58a 100644 --- a/md/clause-9.md +++ b/md/clause-9.md @@ -362,12 +362,13 @@ case of conflict. **redirect** operations are similar, but no actions shall take place within the local [Context Broker]{.HTML-Keyboard}. **auxiliary** [Context Source Registrations]{.HTML-Keyboard} only apply during -context information consumption operations, and any distributed operation -asociated with an **auxiliary** [Context Source Registration]{.HTML-Keyboard} -shall only be triggered if no matching data has been received from all -previously encountered [Context Sources]{.HTML-Keyboard}, so that the -possibility of data retrieval from local and all other matching distributed -[Context Sources]{.HTML-Keyboard} has been exhausted. +context information consumption operations, and any data retrived from a +distributed operation associated with an **auxiliary** [Context Source +Registration]{.HTML-Keyboard} shall only be added to the payload where no +matching data has been received from all previously encountered [Context +Sources]{.HTML-Keyboard}, so that the possibility of data retrieval from local +and all other matching distributed [Context Sources]{.HTML-Keyboard} has been +exhausted. ## 9.4 Matching Context Source registrations -- GitLab From 3909478eb621071ff360d988d034102c71a9c58f Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 21 Nov 2025 16:42:13 +0100 Subject: [PATCH 4/8] Explicitly state that Attributes are removed in turn. --- md/clause-10.md | 522 ++++++++++++++++++++++++++++++++++++++++-------- md/clause-11.md | 30 ++- 2 files changed, 466 insertions(+), 86 deletions(-) diff --git a/md/clause-10.md b/md/clause-10.md index f0c8bfc..57cc36c 100644 --- a/md/clause-10.md +++ b/md/clause-10.md @@ -55,6 +55,7 @@ Implementations shall exhibit the following behaviour: - If an **exclusive** [Context Source Registration]{.HTML-Keyboard} already exists for this Entity id (URI), Attributes from matching input data are forwarded for remote processing: + - For matching Registrations where the Create Entity operation is supported, the operation is forwarded to the registration endpoint. If the endpoint then raises an error, this shall result in an error in case the complete @@ -65,12 +66,14 @@ Implementations shall exhibit the following behaviour: the complete Create Entity operation failed or in a partial success if some parts of it succeeded. - The matching Attributes are then removed from the Fragment and not processed - further. + The Attributes matching to the **exclusive** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. - If any **redirect** [Context Source Registrations]{.HTML-Keyboard} exist that match against the input data, that input data is forwarded for remote processing by one or more matching endpoints: + - For matching Registrations where the Create Entity operation is supported, matching input data is forwarded. If any such endpoint then raises an error, this shall result in an error in case the complete create has failed or in a @@ -80,8 +83,9 @@ Implementations shall exhibit the following behaviour: if the complete Create Entity operation failed or in a partial success if some parts of it succeeded. -- The matching Attributes are then removed from the Fragment and not processed - further. + The Attributes matching to the **redirect** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. - For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that match against the remaining input data, that input data is also forwarded for @@ -143,6 +147,7 @@ Figure: Update Attributes use case Registration]{.HTML-Keyboard} matches against the input data, Attributes from matching input data are forwarded for remote processing. For each matching registration: + - If the Update Attributes operation is supported by the registration (see clause 9), matching input data is forwarded to the Registration endpoint. - If the Update Attributes operation is not supported by the registration, @@ -150,8 +155,8 @@ Figure: Update Attributes use case complete update failed or in a partial success if some parts of the update succeeded. -- The matching Attributes are then removed from the Fragment and not processed - further. +- The matching Attributes are then removed from the Entity Fragment and not + processed further. - If there are remaining Attributes, for any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints @@ -160,15 +165,17 @@ Figure: Update Attributes use case - Then, implementations shall perform a partial update patch operation over the remains of the target Entity as mandated by clause 8.4.2, using the following procedure. -- For each Attribute (Property or Relationship) included by the Entity Fragment - at root level: +- For each Attribute included by the Entity Fragment at root level: + - 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 a _`datasetId`_ is present in the Attribute included by the Entity Fragment: + - If an Attribute instance in the target Entity has the same _`datasetId`_ _`createdAt`_ - If an Attribute instance in the target Entity has the same _`datasetId`_ @@ -186,12 +193,12 @@ Figure: Update Attributes use case - Otherwise the default Attribute instance shall be appended to the target Entity. -- If _`type`_ is included in the Fragment and it includes Entity Type names that - are not yet in the target Entity, add them to the list of Entity Type names of - the target Entity. -- If _`scope`_ is included in the Fragment and the target entity includes - _`scope`_, replace the scope by the one included in the Fragment, otherwise - ignore it. +- If _`type`_ is included in the Entity Fragment and it includes Entity Type + names that are not yet in the target Entity, add them to the list of Entity + Type names of the target Entity. +- If _`scope`_ is included in the Entity Fragment and the target entity includes + _`scope`_, replace the scope by the one included in the Entity Fragment, + otherwise ignore it. #### 10.2.3.5 Output data @@ -244,10 +251,25 @@ The following behaviour shall be exhibited by compliant implementations: (see clause 9.4), an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - The behaviour defined in clause 8.2.3 on JSON-LD validation. -- If an **exclusive** or **redirect** [Context Source - Registration]{.HTML-Keyboard} matches against the input data, the Attributes - from matching input data are forwarded for remote processing. For each - matching registration: +- If an **exclusive** [Context Source Registration]{.HTML-Keyboard} matches + against the input data, the Attributes from matching input data are forwarded + for remote processing. For each matching registration: + + - If the Append Attributes operation is supported by the registration (see + clause 9), matching input data is forwarded to the Registration endpoint. + - If the Append Attributes operation is not supported by the registration, + this shall result in an error of type [Conflict]{.HTML-Error} if the + complete append failed or in a partial success if some parts of the append + succeeded. + + The Attributes matching to the **exclusive** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. + +- If a **redirect** [Context Source Registration]{.HTML-Keyboard} matches + against the input data, the Attributes from matching input data are forwarded + for remote processing. For each matching registration: + - If the Append Attributes operation is supported by the registration (see clause 9), matching input data is forwarded to the Registration endpoint. - If the Append Attributes operation is not supported by the registration, @@ -255,18 +277,22 @@ The following behaviour shall be exhibited by compliant implementations: complete append failed or in a partial success if some parts of the append succeeded. -- The matching Attributes are then removed from the Fragment and not processed - further. + The Attributes matching to the **redirect** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. + - For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints in case the Append Attributes operation is supported. - Then, implementations shall perform an Append Attributes operation over the remains of the target Entity as using the following procedure: - - For each Attribute (Property or Relationship) included by the Entity - Fragment at root level: + + - For each Attribute included by the Entity Fragment at root level: + - If a _`datasetId`_ is present in the Attribute included by the Entity Fragment: + - If no Attribute instance of the same target Entity exists that has the same _`datasetId`_ - If an Attribute instance of the same target Entity exists that has the @@ -287,15 +313,15 @@ The following behaviour shall be exhibited by compliant implementations: - If overwrite is not allowed the existing default Attribute in the target Entity shall be left untouched. - - If _`type`_ is included in the Fragment and it includes Entity Type names - that are not yet in the target Entity, add them to the list of Entity Type - names of the target Entity. - - If _`scope`_ is included in the Fragment and overwrite is allowed, the scope - of the target Entity will become the one included in the Fragment. - Otherwise, the Scopes in the Fragment that are not part of the value of - scope of the target Entity will be appended to the value of the _`scope`_ of - the target Entity. If there is more than one Scope, the value of _`scope`_ - is represented as a JSON array containing all Scopes. + - If _`type`_ is included in the Entity Fragment and it includes Entity Type + names that are not yet in the target Entity, add them to the list of Entity + Type names of the target Entity. + - If _`scope`_ is included in the Entity Fragment and overwrite is allowed, + the scope of the target Entity will become the one included in the Entity + Fragment. Otherwise, the Scopes in the Entity Fragment that are not part of + the value of scope of the target Entity will be appended to the value of the + _`scope`_ of the target Entity. If there is more than one Scope, the value + of _`scope`_ is represented as a JSON array containing all Scopes. #### 10.2.4.5 Output data @@ -334,8 +360,7 @@ Figure: Partial Attribute update use case - 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. +- Target Attribute to be modified, identified by a name. - A JSON-LD document representing an NGSI-LD Attribute Fragment. #### 10.2.5.4 Behaviour @@ -358,6 +383,7 @@ Figure: Partial Attribute update use case Registration]{.HTML-Keyboard} matches against the input data, the Attributes from matching input data are forwarded for remote processing. For each matching registration: + - If the Partial Attribute update operation is supported by the registration (see clause 9), matching input data is forwarded to the Registration endpoint. @@ -376,15 +402,16 @@ Figure: Partial Attribute update use case - 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} - Perform a partial update patch operation on the target Attribute following the - algorithm mandated by clause 8.4.2 If present in the provided NGSI-LD Entity - Fragment, the type of the Attribute has to be the same as the type of the - targeted Attribute fragment, i.e. it is not allowed to change the type of an + algorithm mandated by clause 8.4.2 If present in the provided NGSI-LD + Attribute Fragment, the type of the Attribute has to be the same as the type + of the Attribute fragment, i.e. it is not allowed to change the type of an Attribute. #### 10.2.5.5 Output data @@ -395,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. + + + +::: 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 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 [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 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. + - If a user _`@context`_ has been supplied, the Attribute 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 @@ -431,8 +545,7 @@ Figure: Delete Attribute use case - 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 deleted, identified by a - name. +- Target Attribute to be deleted, identified by a name. - An optional parameter identifying the _`datasetId`_ of the target Attribute instance to be deleted. Otherwise the default Attribute instance is targeted. - An optional flag _`deleteAll`_ indicating whether also all target Attribute @@ -448,6 +561,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 +636,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 @@ -587,9 +702,10 @@ The following behaviour shall be exhibited by compliant implementations: is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see claue 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, Attributes from - matching input data are forwarded. For each matching registration: +- If an **exclusive** [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, @@ -597,8 +713,24 @@ The following behaviour shall be exhibited by compliant implementations: complete Merge Entity operation failed, or in a partial success if some parts of it succeeded. -- The matching Attributes are then removed from the Fragment and not processed - further. + The Attributes matching to the **exclusive** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. + +- If a **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, + this shall result in an error of type [Conflict]{.HTML-Error} in case the + complete Merge Entity operation failed, or in a partial success if some + parts of it succeeded. + + The Attributes matching to the **redirect** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. - For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that match against the remaining input data, that input data is also forwarded in @@ -611,15 +743,17 @@ 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: +- For each Attribute 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. + + - If the Attribute to be merged is represented in a simplified + representation, the _`type`_ of any pre-existing Attribute in the target + entity shall be preserved. - If a common language tag is defined and a _LanguageProperty_ Attribute to be merged is represented as a string, the pre-existing _`languageMap`_ JSON object shall be preserved. The string value shall only replace the @@ -631,7 +765,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 +779,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. @@ -655,15 +793,15 @@ The following behaviour shall be exhibited by compliant implementations: - Otherwise if value is not NGSI-LD Null, the default Attribute instance shall be appended to the target Entity. -- If _`type`_ is included in the Fragment and it includes Entity Type names that - are not yet in the target Entity, add them to the list of Entity Type names of - the target Entity. -- If _`scope`_ is included in the Fragment and overwrite is allowed, the scope - of the target Entity will become the one included in the Fragment. Otherwise, - the Scopes in the Fragment that are not part of the value of _`scope`_ of the - target Entity will be appended to the value of the _`scope`_ of the target - Entity. If there is more than one Scope, the value of _`scope`_ is represented - as a JSON array containing all Scopes. +- If _`type`_ is included in the Entity Fragment and it includes Entity Type + names that are not yet in the target Entity, add them to the list of Entity + Type names of the target Entity. +- If _`scope`_ is included in the Entity Fragment and overwrite is allowed, the + scope of the target Entity will become the one included in the Entity + Fragment. Otherwise, the Scopes in the Entity Fragment that are not part of + the value of _`scope`_ of the target Entity will be appended to the value of + the _`scope`_ of the target Entity. If there is more than one Scope, the value + of _`scope`_ is represented as a JSON array containing all Scopes. #### 10.2.9.5 Output data @@ -710,9 +848,10 @@ Figure: Replace Entity use case error of type [ResourceNotFound]{.HTML-Error} shall be raised. - The behaviour defined in clause 8.2.3 on JSON-LD validation. NGSI-LD Nulls are not supported by this operation. -- 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 an **exclusive** [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 @@ -720,8 +859,25 @@ Figure: Replace Entity use case complete Replace Entity operation failed, or in a partial success if some parts of it succeeded. -- The matching Attributes are then removed from the Fragment and not processed - further. + The Attributes matching to the **exclusive** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. + +- If a **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 + shall result in an error of type [Conflict]{.HTML-Error} in case the + complete Replace Entity operation failed, or in a partial success if some + parts of it succeeded. + + The Attributes matching to the **redirect** [Context Source + Registration]{.HTML-Keyboard} are then removed from the Entity Fragment and + not processed further. + - For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that match against the remaining input data, that input data is also forwarded in the case the Replace Entity operation is supported for remote processing to @@ -763,8 +919,7 @@ Figure: Replace Attribute use case - 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 replaced, identified by a - name. +- Target Attribute to be replaced, identified by a name. - A JSON-LD document representing an NGSI-LD Attribute Fragment. #### 10.2.11.4 Behaviour @@ -780,9 +935,10 @@ Figure: Replace Attribute use case held locally, and no matching registrations apply (see clause 9.4), then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - The behaviour defined in clause 8.2.3 on JSON-LD validation. -- 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 an **exclusive** [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, @@ -790,7 +946,20 @@ Figure: Replace Attribute use case complete Replace Attribute operation failed, or in a partial success if some parts of it succeeded. -- No further processing is required. + No further processing is required. + +- If a **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, + this shall result in an error of type [Conflict]{.HTML-Error} in case the + complete Replace Attribute operation failed, or in a partial success if some + parts of it succeeded. + + No further processing is required. - For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that match against the remaining input data, that input data is also forwarded in @@ -914,6 +1083,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 +1160,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 +1191,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 +1204,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 +1258,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 +1302,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 +1316,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 +1324,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 +1343,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 +1362,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 +1403,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Update a batch of Entities use case ::: @@ -1265,6 +1445,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 +1459,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 +1474,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 +1518,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Merge a batch of Entities use case ::: @@ -1371,6 +1555,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 +1569,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 +1616,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Delete a batch of Entities use case ::: @@ -1459,6 +1646,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 +1660,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 +1783,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 +1800,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 +1824,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 +1840,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 +2067,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 +2076,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 +2096,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 +2114,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 +2142,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 +2163,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 +2175,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 +2254,169 @@ 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 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 @@ -2110,6 +2468,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 +2520,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 @@ -2253,7 +2613,7 @@ Figure: Update subscription use case type [ResourceNotFound]{.HTML-Error} shall be raised. - Execute the behaviour defined in clause 8.2.3 on JSON-LD validation. - If the data types and restrictions expressed by clause 5.2.6.5.2 are not met - by the _Subscription Fragment_, then an error of type + by the Subscription Fragment, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - Term to URI expansion of Attribute names shall be observed as mandated by clause 8.2.4. @@ -2464,6 +2824,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 +2839,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 +2857,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 +2904,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-11.md b/md/clause-11.md index fd17915..b40a1bc 100644 --- a/md/clause-11.md +++ b/md/clause-11.md @@ -151,10 +151,9 @@ The following behaviour shall be exhibited by compliant implementations: as a parameter held locally and no matching registrations apply, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - The behaviour defined in Clause+++clause-8+++root.2.3 on JSON-LD validation. -- If an **exclusive** or **redirect** [Context Source - Registration]{.HTML-Keyboard} matches against the input data, the Attributes - from matching input data are forwarded for remote processing. For each - matching registration: +- If an **exclusive** [Context Source Registration]{.HTML-Keyboard} matches + against the input data, the Attributes from matching input data are forwarded + for remote processing. For each matching registration: - If the "Add Attributes to Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. @@ -164,8 +163,25 @@ The following behaviour shall be exhibited by compliant implementations: Evolution of an Entity"operation failed or in a partial success if some parts of it succeeded. - The matching Attributes are then removed from the Fragment and not processed - further. + The Attributes matching the **exclusive** [Context Source + Registration]{.HTML-Keyboard} are then removed from the EntityTemporal Fragment + and not processed further. + +- If a **redirect** [Context Source Registration]{.HTML-Keyboard} matches against + the input data, the Attributes from matching input data are forwarded for remote + processing. For each matching registration: + - If the "Add Attributes to Temporal Evolution of an Entity" operation is + supported by the matched registration, matching input data is forwarded to + the Registration endpoint. + - If the "Add Attributes to Temporal Evolution of an Entity" operation is not + supported by the matched registration, this shall result in an error of type + [Conflict]{.HTML-Error} if the complete "Add Attributes to Temporal + Evolution of an Entity"operation failed or in a partial success if some + parts of it succeeded. + + The Attributes matching the **redirect** [Context Source + Registration]{.HTML-Keyboard} are then removed from the EntityTemporal Fragment + and not processed further. - For any **inclusive** [Context Source Registrations]{.HTML-Keyboard} that match against the remaining input data, that input data is also forwarded for @@ -173,7 +189,7 @@ The following behaviour shall be exhibited by compliant implementations: - If the target [Temporal Evolution of an Entity]{.HTML-Keyboard} exists locally and matches against the remaining input data, implementations shall do the following: - - For each Attribute instance included by the _EntityTemporal_ Fragment at + - For each Attribute instance included by the EntityTemporal Fragment at root level: - The Attribute (considering term expansion rules as mandated by Clause+++clause-8+++root.2.4) instance(s) shall be added to the target -- GitLab From be36feb7afcd169979eeacec12ef147731c239cb Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 21 Nov 2025 16:51:36 +0100 Subject: [PATCH 5/8] Rewrite order. --- md/clause-9.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/md/clause-9.md b/md/clause-9.md index 8bce58a..bdf92df 100644 --- a/md/clause-9.md +++ b/md/clause-9.md @@ -355,14 +355,17 @@ operations shall occur on the specified Attribute of a given Entity. Operations associated with an **exclusive** [Context Source Registration]{.HTML-Keyboard} are always processed before any other local or distributed operations. +Thereafter, distributed operations triggered by **redirect** [Context Source +Registrations]{.HTML-Keyboard} shall take place. These also indicate that no +additional local or distributed operations shall occur on matching Attributes. + Distributed operations triggered by **inclusive** [Context Source Registrations]{.HTML-Keyboard} can take place in parallel to local operations. When retrieving Entities, the algorithm defined in clause 8.5.3 shall apply in -case of conflict. **redirect** operations are similar, but no actions shall take -place within the local [Context Broker]{.HTML-Keyboard}. +case of conflict. -**auxiliary** [Context Source Registrations]{.HTML-Keyboard} only apply during -context information consumption operations, and any data retrived from a +Finally, **auxiliary** [Context Source Registrations]{.HTML-Keyboard} only apply +during context information consumption operations, and any data retrieved from a distributed operation associated with an **auxiliary** [Context Source Registration]{.HTML-Keyboard} shall only be added to the payload where no matching data has been received from all previously encountered [Context -- GitLab From 1d489187fdedeae759406c4e13d3be9176b4470a Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 21 Nov 2025 17:01:18 +0100 Subject: [PATCH 6/8] Added in error --- md/clause-10.md | 87 ------------------------------------------------- 1 file changed, 87 deletions(-) diff --git a/md/clause-10.md b/md/clause-10.md index 57cc36c..2a1dbf4 100644 --- a/md/clause-10.md +++ b/md/clause-10.md @@ -422,101 +422,14 @@ 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 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 [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 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. - - If a user _`@context`_ has been supplied, the Attribute 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 -- GitLab From c4468a6e5c7a14a30453cfcdd3231854391594bc Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 21 Nov 2025 17:04:26 +0100 Subject: [PATCH 7/8] Added in error --- md/clause-10.md | 155 ------------------------------------------------ 1 file changed, 155 deletions(-) diff --git a/md/clause-10.md b/md/clause-10.md index 2a1dbf4..2808182 100644 --- a/md/clause-10.md +++ b/md/clause-10.md @@ -2167,169 +2167,14 @@ 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 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 -- GitLab From 07f7d5b2c7f23049ff31f19e1a81e8110b6111a4 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 2 Dec 2025 12:27:44 +0100 Subject: [PATCH 8/8] Reformat example. --- md/annex-c.md | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/md/annex-c.md b/md/annex-c.md index 9bc6c17..e5290c6 100644 --- a/md/annex-c.md +++ b/md/annex-c.md @@ -1228,20 +1228,40 @@ individual attribute instances for speed; each is identified by a _`datasetId`_. "speed": [ { "type": "Property", - "avg": [[55.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "max": [[56, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "min": [[55, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "distinctCount": [[2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "totalCount": [[2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], + "avg": [ + [55.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "max": [ + [56, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "min": [ + [55, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "distinctCount": [ + [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "totalCount": [ + [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" }, { "type": "Property", - "avg": [[54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "max": [[54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "min": [[54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "distinctCount": [[1, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], - "totalCount": [[2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]], + "avg": [ + [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "max": [ + [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "min": [ + [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "distinctCount": [ + [1, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], + "totalCount": [ + [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"] + ], "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" } ], -- GitLab