From b6fd70ef2305dac82be7422a852ea1d77a1bfc58 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 16 Dec 2025 17:36:46 +0100 Subject: [PATCH] Add CSS Class to Snapshot --- md/clause-16.md | 217 ++++++++++++++++++++++++++---------------------- md/clause-7.md | 25 +++--- md/clause-8.md | 6 +- 3 files changed, 132 insertions(+), 116 deletions(-) diff --git a/md/clause-16.md b/md/clause-16.md index 6a95db2..828242c 100644 --- a/md/clause-16.md +++ b/md/clause-16.md @@ -2,24 +2,25 @@ ## 16.1 Introduction -Clause+++root describes all operations related to snapshots. Snapshots allow -creating a consistent (within the limits of the possibly distributed NGSI-LD -system) view of the Entities selected by the queries. It allows consuming these -Entities, but also using provision operations for making available predicted and -simulated information, e.g. as needed for digital twins. Implementing the -[Snapshot API]{.HTML-Keyboard} is optional for NGSI-LD systems. +Clause+++root describes all operations related to [Snapshots]{.HTML-Keyboard}. +[Snapshots]{.HTML-Keyboard} allow creating a consistent (within the limits of +the possibly distributed NGSI-LD system) view of the Entities selected by the +queries. It allows consuming these Entities, but also using provision operations +for making available predicted and simulated information, e.g. as needed for +digital twins. Implementing the [Snapshot API]{.HTML-Keyboard} is optional for +NGSI-LD systems. ## 16.2 Create Snapshot ### 16.2.1 Description -This operation allows creating a new snapshot. +This operation allows for the creation of a new [Snapshot]{.HTML-Keyboard}. ### 16.2.2 Use case diagram -A [Context Consumer]{.HTML-Keyboard} can create a new snapshot to have a more -consistent basis for queries on the persisted Entity information as shown in -Figure+++below. +A [Context Consumer]{.HTML-Keyboard} can create a new [Snapshot]{.HTML-Keyboard} +to have a more consistent basis for queries on the persisted Entity information +as shown in Figure+++below. @@ -35,7 +36,7 @@ Figure: Create Snapshot use case ### 16.2.3 Input data -- A JSON-LD document conforming to the Snapshot data type as mandated by +- A JSON-LD document conforming to the _Snapshot_ data type as mandated by clause+++clause-5+++root.2.6.5.4. ### 16.2.4 Behaviour @@ -43,24 +44,25 @@ Figure: Create Snapshot use case - If the data types, cardinalities and restrictions expressed by Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type [BadRequestData]{.HTML-Error} shall be raised. -- If the NGSI-LD endpoint already knows about this Snapshot, as there is an - existing Snapshot whose id (URI) is equivalent, an error of type - [AlreadyExists]{.HTML-Error} shall be raised. -- If the Snapshot document does not include a Snapshot identifier, a new locally - unique identifier (URI) shall be automatically generated by the - implementation. +- If the NGSI-LD endpoint already knows about this [Snapshot]{.HTML-Keyboard}, + as there is an existing [Snapshot]{.HTML-Keyboard} whose id (URI) is + equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. +- If the [Snapshot]{.HTML-Keyboard} document does not include a + [Snapshot]{.HTML-Keyboard} identifier, a new locally unique identifier (URI) + shall be automatically generated by the implementation. - The _`createdAt`_ and _`modifiedAt`_ timestamps are set to the current time of the NGSI-LD system. - The _`snapshotStatus`_ member is set to _`preparation`_. - The _`expiresAt`_ member shall be set, taking into account the _`snapshotLifetime`_ requested, but applying the configured limit of the NGSI-LD system. -- If the Snapshot document does not include a _`snapshotPriority`_, the - _`snapshotPriority`_ shall be set to 5. -- The request returns, confirming the creation of the snapshot to the requesting - [Context Consumer]{.HTML-Keyboard}, providing the Snapshot identifier. The - status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in - Clause+++root.4. The following is executed in the background. +- If the [Snapshot]{.HTML-Keyboard} document does not include a + _`snapshotPriority`_, the _`snapshotPriority`_ shall be set to 5. +- The request returns, confirming the creation of the [Snapshot]{.HTML-Keyboard} + to the requesting [Context Consumer]{.HTML-Keyboard}, providing the + [Snapshot]{.HTML-Keyboard} identifier. The status is accessible to the + [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The + following is executed in the background. - Implementations shall execute the Queries specified in the _`snapshotQueries`_ member, in each case following the behaviour described in Clause+++clause-10+++root.4.3.4. If the size of the respective results require @@ -84,23 +86,25 @@ Figure: Create Snapshot use case result, to ["empty"]{.HTML-Code}, if at least one query or temporal query was executed successfully, but without yielding a result, and to ["failure"]{.HTML-Code} otherwise. -- If the _`endpoint`_ member is present, a Snapshot notification is sent as - described in Clause+++root.8. +- If the _`endpoint`_ member is present, a [Snapshot]{.HTML-Keyboard} + notification is sent as described in Clause+++root.8. ### 16.2.5 Output data -A URI identifying the newly created Snapshot. +A URI identifying the newly created [Snapshot]{.HTML-Keyboard}. ## 16.3 Clone Snapshot ### 16.3.1 Description -This operation allows cloning a snapshot stored in an NGSI-LD system. +This operation allows cloning a [Snapshot]{.HTML-Keyboard} stored in an NGSI-LD +system. ### 16.3.2 Use case diagram -A [Context Consumer]{.HTML-Keyboard} can clone an existing snapshot stored in an -NGSI-LD system as shown in Figure+++below. +A [Context Consumer]{.HTML-Keyboard} can clone an existing +[Snapshot]{.HTML-Keyboard} stored in an NGSI-LD system as shown in +Figure+++below. @@ -116,8 +120,8 @@ Figure: Clone Snapshot use case ### 16.3.3 Input data -- A URI identifying the Snapshot to be cloned. -- A JSON-LD document conforming to the Snapshot data type as mandated by +- A URI identifying the [Snapshot]{.HTML-Keyboard} to be cloned. +- A JSON-LD document conforming to the _Snapshot_ data type as mandated by Clause+++clause-5+++root.2.6.5.4, but without _`snapshotQueriesDetails`_ and _`snapshotQueriesTemporalDetails`_ elements. @@ -126,47 +130,50 @@ Figure: Clone Snapshot use case - If the data types, cardinalities and restrictions expressed by Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type [BadRequestData]{.HTML-Error} shall be raised. -- If the identifier of the Snapshot to be cloned is not found, an error of type - [ResourceNotFound]{.HTML-Error} shall be raised. -- If the Snapshot document includes a Snapshot identifier and there is an - existing Snapshot whose id (URI) is equivalent, an error of type +- If the identifier of the [Snapshot]{.HTML-Keyboard} to be cloned is not found, + an error of type [ResourceNotFound]{.HTML-Error} shall be raised. +- If the [Snapshot]{.HTML-Keyboard} document includes a + [Snapshot]{.HTML-Keyboard} identifier and there is an existing + [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. -- If the Snapshot document does not include a Snapshot identifier, a new locally - unique identifier (URI) shall be automatically generated by the - implementation. +- If the [Snapshot]{.HTML-Keyboard} document does not include a + [Snapshot]{.HTML-Keyboard} identifier, a new locally unique identifier (URI) + shall be automatically generated by the implementation. - The _`createdAt`_ and _`modifiedAt`_ timestamps of the clone are set to the current time of the NGSI-LD system. - The _`snapshotStatus`_ member of the clone is set to _`preparation`_. - The _`expiresAt`_ member shall be set, taking into account the _`snapshotLifetime`_ requested, but applying the configured limit of the NGSI-LD system. -- The request returns, confirming the creation of the cloned Snapshot to the - requesting [Context Consumer]{.HTML-Keyboard}. The status is accessible to the - [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The - following is executed in the background. -- All Entity and Temporal Evolution of Entity data that is part of the Snapshot - to be cloned is copied to the clone Snapshot. +- The request returns, confirming the creation of the cloned + [Snapshot]{.HTML-Keyboard} to the requesting [Context + Consumer]{.HTML-Keyboard}. The status is accessible to the [Context + Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is + executed in the background. +- All Entity and Temporal Evolution of Entity data that is part of the + [Snapshot]{.HTML-Keyboard} to be cloned is copied to the clone + [Snapshot]{.HTML-Keyboard}. - After all information has been stored, the _`snapshotStatus`_ member is set to ["success"]{.HTML-Code}, if cloning was successful, and to ["failure"]{.HTML-Code} otherwise. -- If the _`endpoint`_ member is present, a Snapshot notification is sent as - described in Clause+++root.8. +- If the _`endpoint`_ member is present, a [Snapshot]{.HTML-Keyboard} + notification is sent as described in Clause+++root.8. ### 16.3.5 Output data -A URI identifying the newly created Snapshot. +A URI identifying the newly created [Snapshot]{.HTML-Keyboard}. ## 16.4 Retrieve Snapshot status ### 16.4.1 Description -This operation allows retrieving the status of a Snapshot stored in an NGSI-LD -system. +This operation allows retrieving the status of a [Snapshot]{.HTML-Keyboard} +stored in an NGSI-LD system. ### 16.4.2 Use case diagram -A [Context Consumer]{.HTML-Keyboard} can retrieve the status of a Snapshot from -an NGSI-LD system as shown in Figure+++below. +A [Context Consumer]{.HTML-Keyboard} can retrieve the status of a +[Snapshot]{.HTML-Keyboard} from an NGSI-LD system as shown in Figure+++below. @@ -182,32 +189,34 @@ Figure: Retrieve Snapshot Status use case ### 16.4.3 Input data -Snapshot Id (URI) of the Snapshot whose status is to be retrieved. +[Snapshot]{.HTML-Keyboard} Id (URI) of the [Snapshot]{.HTML-Keyboard} whose +status is to be retrieved. ### 16.4.4 Behaviour -- If the Snapshot Id is not present or it is not a valid URI, then an error of - type [BadRequestData]{.HTML-Error} shall be raised. -- If the identifier provided does not correspond to any existing Snapshot in the - system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. -- Otherwise, implementations shall retrieve the Snapshot status and return it to - the caller. +- If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, + then an error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the identifier provided does not correspond to any existing + [Snapshot]{.HTML-Keyboard} in the system, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- Otherwise, implementations shall retrieve the [Snapshot]{.HTML-Keyboard} + status and return it to the caller. ### 16.4.5 Output data -A JSON-LD object representing the Snapshot status as mandated by -Clause+++clause-5+++root.2.6.5.4. +A JSON-LD object representing the [Snapshot]{.HTML-Keyboard} status as mandated +by Clause+++clause-5+++root.2.6.5.4. ## 16.5 Update Snapshot status ### 16.5.1 Description -This operation allows updating an existing Snapshot. +This operation allows updating an existing [Snapshot]{.HTML-Keyboard}. ### 16.5.2 Use case diagram -A [Context Consumer]{.HTML-Keyboard} can update an existing Snapshot within an -NGSI-LD system as shown in Figure+++below. +A [Context Consumer]{.HTML-Keyboard} can update an existing +[Snapshot]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. @@ -223,15 +232,16 @@ Figure: Update Snapshot Status use case ### 16.5.3 Input data -- Snapshot Id (URI), the target Snapshot. -- A JSON-LD document representing a Snapshot Fragment +- [Snapshot]{.HTML-Keyboard} Id (URI), the target [Snapshot]{.HTML-Keyboard}. +- A JSON-LD document representing a [Snapshot]{.HTML-Keyboard} Fragment ### 16.5.4 Behaviour -- If the Snapshot Id is not present or it is not a valid URI, then an error of - type [BadRequestData]{.HTML-Error} shall be raised. -- If the NGSI-LD System does not know about the target Snapshot, because there - is no existing Snapshot whose id (URI) is equivalent, an error of type +- If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, + then an error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the NGSI-LD System does not know about the target + [Snapshot]{.HTML-Keyboard}, because there is no existing + [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Execute the behaviour defined in Clause+++clause-8+++root.2.3 on JSON-LD validation. @@ -241,24 +251,24 @@ Figure: Update Snapshot Status use case [BadRequestData]{.HTML-Error} shall be raised. - Term to URI expansion of Attribute names shall be observed as mandated by Clause+++clause-8+++root.2.4. -- Then, implementations shall modify the target Snapshot as mandated by - Clause+++clause-8+++root.4.2. +- Then, implementations shall modify the target [Snapshot]{.HTML-Keyboard} as + mandated by Clause+++clause-8+++root.4.2. ### 16.5.5 Output data -A JSON-LD object representing the Snapshot status as mandated by -Clause+++clause-5+++root.2.6.5.4. +A JSON-LD object representing the [Snapshot]{.HTML-Keyboard} status as mandated +by Clause+++clause-5+++root.2.6.5.4. ## 16.6 Delete Snapshot ### 16.6.1 Description -This operation allows deleting an existing Snapshot. +This operation allows deleting an existing [Snapshot]{.HTML-Keyboard}. ### 16.6.2 Use case diagram -A [Context Consumer]{.HTML-Keyboard} can delete a Snapshot within an NGSI-LD -system as shown in Figure+++below. +A [Context Consumer]{.HTML-Keyboard} can delete a [Snapshot]{.HTML-Keyboard} +within an NGSI-LD system as shown in Figure+++below. @@ -274,16 +284,17 @@ Figure: Delete Snapshot use case ### 16.6.3 Input data -- A Snapshot identifier (URI), the target Snapshot. +- A [Snapshot]{.HTML-Keyboard} identifier (URI), the target + [Snapshot]{.HTML-Keyboard}. ### 16.6.4 Behaviour -- If the Snapshot Id is not present or it is not a valid URI, then an error of - type [BadRequestData]{.HTML-Error} shall be raised. -- If the Snapshot id provided does not correspond to any existing Snapshot in - the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be - raised. -- Otherwise implementations shall delete the Snapshot. +- If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, + then an error of type [BadRequestData]{.HTML-Error} shall be raised. +- If the [Snapshot]{.HTML-Keyboard} id provided does not correspond to any + existing [Snapshot]{.HTML-Keyboard} in the system, then an error of type + [ResourceNotFound]{.HTML-Error} shall be raised. +- Otherwise implementations shall delete the [Snapshot]{.HTML-Keyboard}. ### 16.6.5 Output data @@ -293,12 +304,12 @@ None. ### 16.7.1 Description -This operation allows purging selected Snapshots. +This operation allows purging selected [Snapshots]{.HTML-Keyboard}. ### 16.7.2 Use case diagram -A [Context Consumer]{.HTML-Keyboard} can purge Snapshots within an NGSI-LD -system as shown in Figure+++below. +A [Context Consumer]{.HTML-Keyboard} can purge [Snapshots]{.HTML-Keyboard} +within an NGSI-LD system as shown in Figure+++below. @@ -314,8 +325,8 @@ Figure: Purge Snapshots use case ### 16.7.3 Input data -- An NGSI-LD Query to select fitting Snapshots to be purged based on members of - the Snapshot data type (see table 5.2.6.5.4-1), as per +- An NGSI-LD Query to select fitting [Snapshots]{.HTML-Keyboard} to be purged + based on members of the _Snapshot_ data type (see table 5.2.6.5.4-1), as per Clause+++clause-7+++root.2.3. ### 16.7.4 Behaviour @@ -323,7 +334,8 @@ Figure: Purge Snapshots use case - If the NGSI-LD Query is not present or it is not a valid as per Clause+++clause-7+++root.2.3, restricted to members of the Snapshot data type, then an error of type [BadRequestData]{.HTML-Error} shall be raised. -- Implementations shall purge the Snapshots fitting the NGSI-LD Query. +- Implementations shall purge the [Snapshots]{.HTML-Keyboard} fitting the + NGSI-LD Query. ### 16.7.5 Output data @@ -331,21 +343,24 @@ None. ## 16.8 Snapshot status notification behaviour -A Snapshot status notification allows the subscriber, typically the creator of -the Snapshot, to be notified when the Snapshot is ready, or in case of any -problems or updates. Implementations shall exhibit the following behaviour: +A [Snapshot]{.HTML-Keyboard} status notification allows the subscriber, +typically the creator of the [Snapshot]{.HTML-Keyboard}, to be notified when the +[Snapshot]{.HTML-Keyboard} is ready, or in case of any problems or updates. +Implementations shall exhibit the following behaviour: - SnapshotNotification (Clause+++clause-5+++root.2.6.9.3) messages can only be sent, if the _`endpoint`_ member is set. - SnapshotNotification messages are sent to the URI specified in the - _`endpoint`_ member of the Snapshot status. -- The information in the _`receiverInfo`_ member of the Snapshot status shall be - added to the SnapshotNotification message in the way required for the binding - protocol. -- Snapshot Status Notifications shall be sent after all the specified Snapshot - queries have been executed, the query results have been integrated and the - Snapshot status has been updated accordingly. -- Snapshot status Notifications shall also be sent after any Snapshot status - update, e.g. informing about the actual updated _`expiresAt`_ timestamp. + _`endpoint`_ member of the [Snapshot]{.HTML-Keyboard} status. +- The information in the _`receiverInfo`_ member of the + [Snapshot]{.HTML-Keyboard} status shall be added to the SnapshotNotification + message in the way required for the binding protocol. +- [Snapshot]{.HTML-Keyboard} Status Notifications shall be sent after all the + specified [Snapshot]{.HTML-Keyboard} queries have been executed, the query + results have been integrated and the [Snapshot]{.HTML-Keyboard} status has + been updated accordingly. +- [Snapshot]{.HTML-Keyboard} status Notifications shall also be sent after any + [Snapshot]{.HTML-Keyboard} status update, e.g. informing about the actual + updated _`expiresAt`_ timestamp. - The SnapshotNotification shall be as mandated by Clause+++clause-5+++root.2.6.9.3. diff --git a/md/clause-7.md b/md/clause-7.md index da3c74d..cd32022 100644 --- a/md/clause-7.md +++ b/md/clause-7.md @@ -105,10 +105,10 @@ to: describe them, defined when [Context Sources]{.HTML-Keyboard} are registered (target is the name of a [Context Source]{.HTML-Keyboard} Property member of the CSourceRegistration, see Table 5.2.9-1). -- filter out [Snapshots]{.HTML-Keyboard} by the values of the Snapshot data type - members, i.e. when filtering [Snapshots]{.HTML-Keyboard}, only the names of - the members defined for Snapshot in Table 5.2.43-1 are allowed values for - [AttrName]{.HTML-Sample}. +- filter out [Snapshots]{.HTML-Keyboard} by the values of the _Snapshot_ data + type members, i.e. when filtering [Snapshots]{.HTML-Keyboard}, only the names + of the members defined for [Snapshot]{.HTML-Keyboard} in Table 5.2.43-1 are + allowed values for [AttrName]{.HTML-Sample}. #### 7.2.3.2 Query Language Definition @@ -2107,11 +2107,12 @@ type [NoMultiTenantSupport]{.HTML-Error} Context information can be dynamic, e.g. when a query result contains many Entities, and the user has to paginate through the result set, the values encountered later may be from a much later point in time than earlier results, -making them incomparable. To get more consistent results, the Snapshot concept -is introduced, which can be optionally implemented by Context Brokers. It -enables "freezing" the result by retrieving all results immediately and -persisting them locally. [Context Consumers]{.HTML-Keyboard} can then query and -analyse the Snapshot in a much more consistent way. +making them incomparable. To get more consistent results, the +[Snapshot]{.HTML-Keyboard} concept is introduced, which can be optionally +implemented by Context Brokers. It enables "freezing" the result by retrieving +all results immediately and persisting them locally. [Context +Consumers]{.HTML-Keyboard} can then query and analyse the +[Snapshot]{.HTML-Keyboard} in a much more consistent way. This is especially relevant for distributed cases, where information initially was distributed across multiple [Context Brokers]{.HTML-Keyboard} and [Context @@ -2142,9 +2143,9 @@ protocol binding specific. The [Snapshot]{.HTML-Keyboard} concept is orthogonal to the [Tenant]{.HTML-Keyboard} concept (see clause 7.8). [Snapshots]{.HTML-Keyboard} can also be created on [Tenants]{.HTML-Keyboard}. To execute an operation on a -Snapshot created on a [Tenant]{.HTML-Keyboard}, both [Snapshot]{.HTML-Keyboard} -and [Tenant]{.HTML-Keyboard} (see clause 7.8.2) have to be specified for an API -operation. +[Snapshot]{.HTML-Keyboard} created on a [Tenant]{.HTML-Keyboard}, both +[Snapshot]{.HTML-Keyboard} and [Tenant]{.HTML-Keyboard} (see clause 7.8.2) have +to be specified for an API operation. If an implementation determines that it is low on resources, it may delete one or more snapshots. For determining the order in which snapshots are to be diff --git a/md/clause-8.md b/md/clause-8.md index dd1c946..73d8b87 100644 --- a/md/clause-8.md +++ b/md/clause-8.md @@ -725,6 +725,6 @@ If the request limits the execution of the operation to the local scope, [Context Source Registrations]{.HTML-Keyboard} from the [Context Registry]{.HTML-Keyboard} will not be used. -Operations on a Snapshot (see Clause+++clause-7+++7.9) are always implicitly -local scope, overriding setting a local scope to false, i.e. such a setting is -to be ignored by implementations. +Operations on a [Snapshot]{.HTML-Keyboard} (see Clause+++clause-7+++7.9) are +always implicitly local scope, overriding setting a local scope to false, i.e. +such a setting is to be ignored by implementations. -- GitLab