diff --git a/md/annex-b.md b/md/annex-b.md index 6f85bf64dd6b58f71a6ea7a1a5b54149808e4afc..315e02fd6cfa94801c124113fda6e9195353b17c 100644 --- a/md/annex-b.md +++ b/md/annex-b.md @@ -117,7 +117,7 @@ Such definition has been tested using [i.19]. "@id": "ngsi-ld:deletedAt", "@type": "DateTime" }, - "description": "http://purl.org/dc/terms/description", + "description": "http://purl.org/dc/terms/description", "detail": "ngsi-ld:detail", "endAt": { "@id": "ngsi-ld:endAt", diff --git a/md/clause-10.md b/md/clause-10.md index a389a86f8e058b27878c0d7eb61eb4f64d1d841d..539418f561a25050ff87a23425b9010a056065f7 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,10 @@ 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, @@ -255,18 +262,37 @@ 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 **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, + 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 **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 @@ -431,8 +458,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 +474,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 +549,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 +615,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 +626,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 +656,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 +678,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 +692,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 +706,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 +761,25 @@ 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 + 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 **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 @@ -720,8 +787,10 @@ 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 **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 +832,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 +848,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 +859,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 +996,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 +1073,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 +1104,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 +1117,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 +1171,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 +1215,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 +1229,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 +1237,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 +1256,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 +1275,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 +1316,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Update a batch of Entities use case ::: @@ -1265,6 +1358,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 +1372,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 +1387,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 +1431,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Merge a batch of Entities use case ::: @@ -1371,6 +1468,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 +1482,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 +1529,11 @@ NGSI-LD system as shown in Figure+++below. -::: FL +::: FL ::: -::: TF +::: TF Figure: Delete a batch of Entities use case ::: @@ -1459,6 +1559,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 +1573,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 +1696,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 +1713,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 +1737,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 +1753,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]{.HTML-Code} 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 @@ -1875,6 +1983,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; @@ -1883,6 +1992,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; @@ -1902,8 +2012,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 @@ -1918,6 +2030,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 @@ -1945,6 +2058,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 @@ -1965,6 +2079,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 @@ -1976,12 +2091,13 @@ 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]{.HTML-Code} 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 - specified version of the NGSI-LD specification as mandated in clause 9.5.3, - and return a [Preference-Applied]{.HTML-Code} Header set to - ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. + +- If the [Prefer]{.HTML-Code} 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 + specified version of the NGSI-LD specification as mandated in clause 9.5.3, + and return a [Preference-Applied]{.HTML-Code} Header set to + ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. - If the Accept Header is set to ["application/geo+json",]{.HTML-Code} the response shall be a GeoJSON _FeatureCollection_ as mandated by clause @@ -2115,6 +2231,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 @@ -2166,6 +2283,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 @@ -2258,7 +2376,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. @@ -2469,6 +2587,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 @@ -2483,6 +2602,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`_ @@ -2500,6 +2620,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; @@ -2546,6 +2667,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 d1ddeb34b170bedc1baf6ae0cdf31288c59fca73..114d261d384fa4c87e733929c1666abc0667b762 100644 --- a/md/clause-11.md +++ b/md/clause-11.md @@ -54,6 +54,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 or Update (Upsert) Temporal Evolution of an Entity" operation is supported, the operation is forwarded to the registration endpoint. If the endpoint then raises an error, this @@ -72,6 +73,7 @@ Implementations shall exhibit the following behaviour: - 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 or Update (Upsert) Temporal Evolution of an Entity" operation is supported, matching input data is forwarded. If any such endpoint then raises an error, this shall result in @@ -151,10 +153,10 @@ 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 +166,26 @@ 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,8 +193,8 @@ 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 - root level: + - 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 [Temporal Evolution of an Entity]{.HTML-Keyboard}. @@ -237,6 +257,7 @@ Figure: Delete Attribute from Temporal Evolution of an Entity 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 "Delete Attribute from Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. @@ -326,6 +347,7 @@ Figure: Modify Attribute Instance in Temporal Evolution of an Entity 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 "Modify Attribute instance in Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. @@ -412,6 +434,7 @@ Figure: Delete Attribute Instance from Temporal Evolution of an Entity 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 "Delete Attribute instance from Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. @@ -484,6 +507,7 @@ Figure: Delete Temporal Evolution of an Entity 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 "Delete Temporal Evolution of Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. @@ -783,12 +807,14 @@ Clause+++clause-8+++root.6 ), no further restrictions have to be provided. temporal property (by default _observedAt_) within the concerned temporal interval. - Otherwise, + - Let S be the set of selected Entities i.e. the query result set. - If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope 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): + - If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter. - If an id pattern is provided, keep in S only those Entities whose id diff --git a/md/clause-12.md b/md/clause-12.md index 3e0e020f45cc2336b1f3f2343a8ba60f6a38245c..519c826b1ad3d99c91f28e2e4d74793b2698b903 100644 --- a/md/clause-12.md +++ b/md/clause-12.md @@ -354,6 +354,7 @@ Figure: Discover context source registrations use case here to identify relevant GeoProperties and for geographical scoping) as per Clause+++clause-7+++7.2.4 (optional). - In the case of GeoJSON representation: + - The name of the _GeoProperty_ attribute to use as the geometry for the GeoJSON representation as mandated by Clause+++clause-5+++5.3.3 (optional). - A _datasetId_ specifying which instance of the value is to be selected if @@ -506,6 +507,7 @@ Figure: Subscribe Context Source Registration use case - The behaviour shall be as described in Clause+++clause-10+++10.5.2.4, restricted to the local case (where Subscriptions cannot be received from remote Brokers), with the following exceptions: + - If all checks described in Clause+++clause-10+++10.5.2.4 pass, implementations shall add a new [Context Source Registration]{.HTML-Keyboard} Subscription. The parameters of the created @@ -541,6 +543,7 @@ Figure: Subscribe Context Source Registration use case ["modifiedAt"or "deletedAt",]{.HTML-Code} the temporal query is matched against the _`managementInterval`_ (if present). If the relevant interval is not present, there is no match: + - The semantics of the match is that the _`timeAt`_ in the case of the ["before"]{.HTML-Code} and ["after"]{.HTML-Code} relation is contained in or is an endpoint of a time period included in the specified time @@ -783,6 +786,7 @@ following exceptions: information relevant for the subscription, in particular only matching _RegistrationInfo_ elements. - A csource notification shall be sent as follows: + - The structure of the csource notification message shall be as mandated by Clause+++clause-5+++5.2.6.9.4. - A csource notification shall be sent to the _`endpoint`_. @@ -790,6 +794,7 @@ following exceptions: - The _`notification.lastNotification`_ member shall be updated with the current timestamp. - If the notification is sent successfully: + - Update _`notification.lastSuccess`_ with the current timestamp. - If the notification is not sent successfully: diff --git a/md/clause-7.md b/md/clause-7.md index ce597642cd966e5a8dc90674002c0bfaa11af6c7..da3c74df08477f6844b9cbabbf6ea737dfd664f4 100644 --- a/md/clause-7.md +++ b/md/clause-7.md @@ -693,18 +693,21 @@ described as follows and shall be supported by compliant implementations: - **Unequal** operator (production rule named [unequal]{.HTML-Sample}). A matching entity shall contain the target element and meet none of the conditions defined in clause 7.2.3.4 + - If the data type of the target value and the data type of the Query Term value are different, then they shall be considered unequal. - **Greater than** operator (production rule named [greater]{.HTML-Sample}). For an entity to match, it shall contain the target element and the target value has to be strictly greater than the Query Term value: + - If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching. - **Less than** operator (production rule named [less]{.HTML-Sample}). For an entity to match, it shall contain the target element and the target value shall be strictly less than the value: + - If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching. @@ -719,6 +722,7 @@ described as follows and shall be supported by compliant implementations: - **Match pattern** (production rule named [patternOp]{.HTML-Sample}). A matching entity shall contain the target element and the target value shall be in the L(R) of the regular pattern specified by the Query Term: + - If the target value data type is different than _String_ then it shall be considered as not matching. @@ -1165,6 +1169,7 @@ The semantics of the different geospatial relationships defined above is as follows, and shall be supported by compliant implementations: - **near** statement (production rule named [nearRel]{.HTML-Sample}): + - [maxDistance]{.HTML-Sample} modifier. For an entity to match it has to be within the buffer geometric object (as defined by [n.21]) given by the reference geometry, with distance (in meters) equal to the number conveyed @@ -2002,9 +2007,9 @@ Entities could result in payloads of an excessive length. Therefore to mitigate this, the default depth of retrieval (or _`joinLevel`_) shall be set to one, meaning that only one level of _Relationships_ are traversed, though this may be overridden on request. Furthermore, to avoid unnecessary duplication, whenever a -[Linked Entity]{.HTML-Keyboard} has already been previously encountered during graph -traversal at a shallower depth, its [Linked Entities]{.HTML-Keyboard} shall not undergo -further expansion for a second time. +[Linked Entity]{.HTML-Keyboard} has already been previously encountered during +graph traversal at a shallower depth, its [Linked Entities]{.HTML-Keyboard} +shall not undergo further expansion for a second time. ## 7.8 Tenants diff --git a/md/clause-9.md b/md/clause-9.md index a7e2ce6c4a2bdd0f3883df5844ab56b212a8c3f1..bdf92df2aa43f601fa8b070c65f0361b15c74b75 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,32 @@ 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 Precedence 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. + +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. + +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 +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