From edb1bf34e9cd7f3f15d1c94a0e4b55be3cf28de1 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Mon, 24 Nov 2025 15:50:56 +0000 Subject: [PATCH 1/8] Updated clause 6.4.7, fixing the pagination for temporal instances --- md/clause-6.md | 92 +++++++++++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 39 deletions(-) diff --git a/md/clause-6.md b/md/clause-6.md index b6172e1..007b0d8 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -683,47 +683,61 @@ Table: Pagination: offset parameter -Temporal representation of resources adds an additional dimension to the -pagination. Depending on the requested time range, the response will contain -multiple instances of the requested Attribute, and therefore an additional -pagination mechanism for those temporal representations is required, in order to -limit the time range of the response. If no limits are specified, a default -limit is enforced, depending on implementation specific configurations. For HTTP -operations on [Temporal Evolution of Entities]{.HTML-Keyboard}, implementations +As defined in [n.1] ~clause 7.4.5, there is an additional temporal dimension +to pagination that limits the number of Attribute instances for any Attribute +in a response. + +If no limits are specified, a default limit is enforced, depending on implementation +specific configurations. For HTTP operations on +[Temporal Evolution of Entities]{.HTML-Keyboard}, implementations shall use the Partial Content Response (206) as specified by IETF RFC 7233 [n.17], ~clause 4.1, if the implementation is not able to respond with the full -representation at once. In this case, for requests where the parameter _`lastN`_ -is present, pagination shall happen "backwards" (from the most recent to the -least recent timestamp in the requested time range). For requests without the -parameter _`lastN`_, pagination shall happen "forwards" (from the least recent -to the most recent timestamp in the requested time range). - -This is achieved by including the ["Content-Range"]{.HTML-Code} header field -with the following contents: - -- ["unit"]{.HTML-Code} shall be equal to ["DateTime"]{.HTML-Code}; -- ["range-start"]{.HTML-Code} and ["range-end"]{.HTML-Code} shall be of type - _[DateTime]{.HTML-Definition}._ They depend on the requested time relationship - _`timerel`_ (as defined by [n.1] ~clause 7.2.6), as follows: - - - If the _`lastN`_ parameter is present, pagination shall happen "backwards": - - - ["range-start"]{.HTML-Code} shall be equal to ["timeAt"]{.HTML-Code} for - requests with _`timerel=before`_, ["endTimeAt"]{.HTML-Code} for requests - with _`timerel=between`_, or the most recent timestamp in the range of the - response, for requests with _`timerel=after`_; - - ["range-end"]{.HTML-Code} shall be equal to the least recent timestamp in - the range of the response; - - ["size"]{.HTML-Code} shall be equal to the requested _`lastN`_. - - - If the _`lastN`_ parameter is **not** present, pagination shall happen - "forwards": - - ["range-start"]{.HTML-Code} shall be equal to _`timeAt`_ for requests with - _`timerel=after`_ or _`timerel=between`_, or the least recent timestamp in - the range of the response, for requests with _`timerel=before`_; - - ["range-end"]{.HTML-Code} shall be equal to the most recent timestamp in - the range of the response; - - ["size"]{.HTML-Code} shall be equal to ["\*"]{.HTML-Code}. +representation at once. + +In this case, for requests where the parameter _`firstN`_ is present the +pagination shall happen in ascending order, with the limit being the value +assigned to _`firstN`_ or the maximum limit configured, whichever is +smaller. + +In case the parameter _`lastN`_ is present, the pagination shall +happen in descending order, with the limit being the value assigned to +_`lastN`_ or the maximum limit configured, whichever is smaller. +If neither _`firstN`_ nor _`lastN`_ is present, ascending order is assumed +with the configured maximum limit as page size. + +Particularly, to flag the existence of pages related to the temporal dimension +that could be retrieved when dealing with query operations involving pagination, +NGSI-LD Systems implementing the HTTP binding shall use the HTTP Link header +field as mandated by IETF RFC 8288 [n.13], ~clause 3, as follows: + +- The pointers to the next page, i.e. in ascending order of the Attribute + timestamps, and previous page, i.e. in descending order of the Attribute + timestamps shall be serialized as link-value elements. The content of such + link-value(s) shall be: + + - For the next page, the Link Target shall be a URI-reference that could be + dereferenced by an NGSI-LD Client to retrieve the next page of NGSI-LD + Elements with the respective Attribute instances. In addition, the Link + Relation Type shall be equal to ["intervalafter"]{.HTML-Code}, registered + under the IANA Registry of Link Relation Types [n.16]. + - For the previous page, the Link Target shall be a URI-reference that could + be dereferenced by an NGSI-LD Client to retrieve the previous page of + NGSI-LD Elements with respective Attribute instances. In addition, the + Link Relation Type shall be equal to ["intervalbefore"]{.HTML-Code}, + registered under the IANA Registry of Link Relation Types [n.16]. + + - At least, the ["type"]{.HTML-Code} Link Target Attribute shall be included by + the previously described serialized Link Header, as mandated by IETF RFC 8288 + [n.13], clause 3.4, and its value shall be exactly equal to the media type + resulting from the original request made by the NGSI-LD Client (the request + that triggered the current pagination iteration). + +If the transparent pagination option as described in [n.1] ~clause 7.2.3 is +used, the URI-references for the ["intervalafter"]{.HTML-Code} and +["intervalbefore"]{.HTML-Code} link to the next and previous pages respectively +should include the _`offset`_ parameter as specified in Table+++above, giving the +Context Consumer more control, i.e. to jump to a desired set of elements in the +results using _`offset`_. ### 6.4.8 Tenant specification -- GitLab From d4bfe66f58c50694bad08a5593ad4ebec1dd66a1 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Mon, 24 Nov 2025 17:10:03 +0000 Subject: [PATCH 2/8] Added offsetN parameter --- md/clause-6.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/md/clause-6.md b/md/clause-6.md index 007b0d8..06b0400 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -735,9 +735,28 @@ field as mandated by IETF RFC 8288 [n.13], ~clause 3, as follows: If the transparent pagination option as described in [n.1] ~clause 7.2.3 is used, the URI-references for the ["intervalafter"]{.HTML-Code} and ["intervalbefore"]{.HTML-Code} link to the next and previous pages respectively -should include the _`offset`_ parameter as specified in Table+++above, giving the -Context Consumer more control, i.e. to jump to a desired set of elements in the -results using _`offset`_. +should include the _`offsetN`_ parameter as specified in Table+++below, giving the +Context Consumer more control, i.e. to jump to a desired set of Attribute instances +in the results using _`offsetN`_. + + + +::: TH +Table: Pagination: offsetN parameter +::: + +::: TAL ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+===========================================================================================================================================================================================================================================================================================================================================+ +| offsetN | Integer | 0..1 | Only values greater or equal to 0. | +| | | | | +| | | | It defines the offset of the Attribute instance that shall be retrieved from the beginning or end of the result set depending on whether the retrieval is in ascending or descending order. If offsetN is set to a value larger than the result set, the offsetN should be assumed to be equal to the size of the result set, | +| | | | i.e. only the last element of the result set is to be returned if there are any results. | ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + ### 6.4.8 Tenant specification -- GitLab From 2fcbd50b2de81c6c474158c99933a99205d0a862 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 25 Nov 2025 13:56:27 +0000 Subject: [PATCH 3/8] Edit clause-6.md --- md/clause-6.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/md/clause-6.md b/md/clause-6.md index 06b0400..dac801c 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -687,23 +687,22 @@ As defined in [n.1] ~clause 7.4.5, there is an additional temporal dimension to pagination that limits the number of Attribute instances for any Attribute in a response. -If no limits are specified, a default limit is enforced, depending on implementation -specific configurations. For HTTP operations on -[Temporal Evolution of Entities]{.HTML-Keyboard}, implementations -shall use the Partial Content Response (206) as specified by IETF RFC 7233 -[n.17], ~clause 4.1, if the implementation is not able to respond with the full -representation at once. +For HTTP operations on [Temporal Evolution of Entities]{.HTML-Keyboard}, +implementations shall use the Partial Content Response (206) as specified by +IETF RFC 7233 [n.17], ~clause 4.1, if the implementation is not able to respond +with the full representation at once. In this case, for requests where the parameter _`firstN`_ is present the pagination shall happen in ascending order, with the limit being the value -assigned to _`firstN`_ or the maximum limit configured, whichever is -smaller. +assigned to _`firstN`_ or the default maximum limit configured, whichever is +smaller. The default maxiumum limit is implementation specific. In case the parameter _`lastN`_ is present, the pagination shall happen in descending order, with the limit being the value assigned to _`lastN`_ or the maximum limit configured, whichever is smaller. + If neither _`firstN`_ nor _`lastN`_ is present, ascending order is assumed -with the configured maximum limit as page size. +with the configured default maximum limit. Particularly, to flag the existence of pages related to the temporal dimension that could be retrieved when dealing with query operations involving pagination, -- GitLab From 3239071c3cadb67ec5a29e3c971032ebf5be89ee Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 25 Nov 2025 14:07:27 +0000 Subject: [PATCH 4/8] Corrected indentation --- md/clause-6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/md/clause-6.md b/md/clause-6.md index dac801c..e216b5b 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -725,7 +725,7 @@ field as mandated by IETF RFC 8288 [n.13], ~clause 3, as follows: Link Relation Type shall be equal to ["intervalbefore"]{.HTML-Code}, registered under the IANA Registry of Link Relation Types [n.16]. - - At least, the ["type"]{.HTML-Code} Link Target Attribute shall be included by +- At least, the ["type"]{.HTML-Code} Link Target Attribute shall be included by the previously described serialized Link Header, as mandated by IETF RFC 8288 [n.13], clause 3.4, and its value shall be exactly equal to the media type resulting from the original request made by the NGSI-LD Client (the request -- GitLab From 72bc7ebfc2b23bcaa71a8bb5a666bc4f498f8ae7 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Wed, 26 Nov 2025 10:08:23 +0000 Subject: [PATCH 5/8] Added table with firstN and lastN for temporal pagination (same as for limit in the general case) Removed the 206 response to align with general pagination --- md/clause-6.md | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/md/clause-6.md b/md/clause-6.md index e216b5b..7e30098 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -685,16 +685,35 @@ Table: Pagination: offset parameter As defined in [n.1] ~clause 7.4.5, there is an additional temporal dimension to pagination that limits the number of Attribute instances for any Attribute -in a response. +in a response. Implementations shall support the HTTP query parameter specified in +Table+++below. + + -For HTTP operations on [Temporal Evolution of Entities]{.HTML-Keyboard}, -implementations shall use the Partial Content Response (206) as specified by -IETF RFC 7233 [n.17], ~clause 4.1, if the implementation is not able to respond -with the full representation at once. +::: TH +Table: Pagination: firstN and lastN parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+=====================================================================================================================================================================================================================+ +| firstN | Positive Integer| 0..1 | Only values greater than 0. | +| | | | | +| | | | Only the first n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to offsetN parameter if specified. | ++-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastN | Positive Integer| 0..1 | Only values greater than 0. | +| | | | | +| | | | Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to offsetN parameter if specified. | ++-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + -In this case, for requests where the parameter _`firstN`_ is present the -pagination shall happen in ascending order, with the limit being the value -assigned to _`firstN`_ or the default maximum limit configured, whichever is +For HTTP requests on [Temporal Evolution of Entities]{.HTML-Keyboard}, +where the parameter _`firstN`_ is present the pagination shall happen in +ascending order, with the limit being the value assigned to _`firstN`_ +or the default maximum limit configured, whichever is smaller. The default maxiumum limit is implementation specific. In case the parameter _`lastN`_ is present, the pagination shall -- GitLab From b676e8d595bd3d3f47e3197eeea41ec4813e1a86 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 2 Dec 2025 08:51:03 +0000 Subject: [PATCH 6/8] minor update --- md/clause-6.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/md/clause-6.md b/md/clause-6.md index 7e30098..8e74fc9 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -750,8 +750,8 @@ field as mandated by IETF RFC 8288 [n.13], ~clause 3, as follows: resulting from the original request made by the NGSI-LD Client (the request that triggered the current pagination iteration). -If the transparent pagination option as described in [n.1] ~clause 7.2.3 is -used, the URI-references for the ["intervalafter"]{.HTML-Code} and +If the transparent pagination option as described in [n.1] ~clause 7.2.3 is used, +the URI-references for the ["intervalafter"]{.HTML-Code} and ["intervalbefore"]{.HTML-Code} link to the next and previous pages respectively should include the _`offsetN`_ parameter as specified in Table+++below, giving the Context Consumer more control, i.e. to jump to a desired set of Attribute instances -- GitLab From 7560af3268110599a1febf92dbb5d2783d43b550 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 16 Dec 2025 16:21:32 +0000 Subject: [PATCH 7/8] Split general pagination and temporal pagination into different subclauses --- md/clause-6.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/md/clause-6.md b/md/clause-6.md index 8e74fc9..9c41f9b 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -594,6 +594,16 @@ parameter will result in a 400 [BadRequest]{.HTML-Error} error. ### 6.4.7 Pagination +#### 6.4.7.1 Introduction + +This clause introduces the HTTP binding of NGSI-LD pagination. Clause 6.4.7.2 +introduces the general pagination that applies to all NGSI-LD results, +whereas clause 6.4.7.3 introduces temporal pagination, a second level of +pagination, used in the temporal API to paginate Attribute instances in the +[Temporal Evolution of Entities]{.HTML-Keyboard}. + +#### 6.4.7.2 General pagination + For HTTP operations corresponding to the operations listed in [n.1] ~clause 7.4 (see Table 5-1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in @@ -683,6 +693,8 @@ Table: Pagination: offset parameter +#### 6.4.7.3 Temporal pagination + As defined in [n.1] ~clause 7.4.5, there is an additional temporal dimension to pagination that limits the number of Attribute instances for any Attribute in a response. Implementations shall support the HTTP query parameter specified in -- GitLab From 46cc7480f2395838b424f50d9d059539d8ddc1cf Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 16 Dec 2025 17:02:25 +0000 Subject: [PATCH 8/8] Added example for temporal pagination link header in Clause A.5 --- md/annex-a.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/md/annex-a.md b/md/annex-a.md index 6c1c980..ebd0a21 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -386,6 +386,20 @@ _`brandName`_ attribute is omitted in the response. + + +>>> [!tip] EXAMPLE 3: + +Give back the temporal evolution of the attribute _`speed`_ of +Entities of type ["Vehicle"]{.HTML-Code} whose _`brandName`_ +attribute is not ["Mercedes"]{.HTML-Code} between the 1st of August +at noon and the 1st of August at 01 PM, but only provide +2 instances of the attribute speed at a time, leading to pagination + +>>> + + + ### A.5.2 HTTP request #1 **GET** @@ -494,6 +508,61 @@ _`brandName`_ attribute is omitted in the response. ] ``` +### A.5.6 HTTP request #3 + +**GET** +[/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&firstN=2]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/**ld+json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +### A.5.7 HTTP response #2 + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} + +- [Link: + </ngsi-ld/v1/temporal/entities/?type=Vehicle?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&firstN=2&offsetN=2>; + rel="intervalafter"; type="application/ld+json"]{.HTML-Code} + +**Response Body** + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "value": 120, + "observedAt": "2018-08-01T12:03:00Z" + }, + { + "type": "Property", + "value": 80, + "observedAt": "2018-08-01T12:05:00Z" + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +] +``` + + + ## A.6 Temporal Query (simplified representation) ### A.6.1 Introduction -- GitLab