With reference to: https://jsonapi.org/profiles/ethanresnick/cursor-pagination/#auto-id--item-cursors

It is stated that item cursors MUST be a cursor that (at the time of the response) “falls on” the item it is returned with.

However,

1. when page[after] is provided, the returned paginated data MUST have as its first item the item that is immediately after the cursor in the results list.
2. when page[before] is provided, the last item returned in the paginated data MUST be the item that is closest to, but still before, the cursor in the unpaginated results list.

Where the contradiction lies is in the following excerpt from the Item Cursors section:

With this response, clients could use page[before]=someOpaqueString or page[after]=someOpaqueString to paginate from person 3 in either direction.

How are item cursors, when passed as parameter values to either page[after] or page[before] supposed to yield paginated data that falls ON the item? Does falling on the item implicate that the first item of the paginated is the item itself?

If the answer is yes, that the first item in the paginated data should be the item pointed to by the cursor itself, then what is the minimum exact required information that needs to be encoded into the item cursor itself then?

Generally, for page[after] and page[before] parameters, on the server side, I would expect the server-side implementation for yielding the paginated data to be something like the following (assuming sent_at and id are columns which data are sorted against and the paginated data is limited to 20 items):

page[after]:

SELECT * FROM messages WHERE (sent_at, id) > $1 LIMIT 20;

page[before]:

SELECT * FROM messages WHERE (sent_at, id) < $1 LIMIT 20;

To allow for item cursor to yield paginated data where the first item is the item pointed to by the cursor itself, the cursor would need to have some indicator that would amend the server-side implementation to yielding the paginated data like so:

page[after]:

SELECT * FROM messages WHERE (sent_at, id) >= $1 LIMIT 20;

page[before]:

SELECT * FROM messages WHERE (sent_at, id) <= $1 LIMIT 20;

The use case for getting clarity on this is, suppose you have a messenger where you have conversations, and each conversation comprise of a list of messages.

The messenger has a search feature where you can search all previous messages.

We would want clicking on any one of the search results to open up the conversation, where the first message shown in the conversation is the search result itself.

Is this something that Item Cursors specify in the cursor pagination profile for JSON-API?