Clarify pagination continuation and sorting rules

[Mehrn0ush]

This PR clarifies the opaque pagination contract in spec/openapi.yaml and addresses issues #249, #250, and #251.

The changes define deterministic ordering rules, clarify hasNext / nextPageToken behavior, and specify how pageToken interacts with query parameters and path-scoped resources.

Changes

Deterministic pagination ordering (#249)

• Define deterministic ordering for paginated results.
• Product, component, product release, and component release results are ordered first by the selected sortField, then by uuid as a deterministic secondary tie-breaker.
• Collection pagination uses collection-specific ordering and does not rely on uuid because collection revisions may share the same UUID.
• Clarify release version sorting semantics and explicitly state that semantic-version precedence is not implied.
• Define ordering behavior for missing releaseDate values.
• Fix /componentReleases to use sort-field-component-release instead of sort-field-component.

hasNext and nextPageToken (#250)

• Remove nextPageToken from required pagination response fields.
• Specify that nextPageToken MUST be present when hasNext is true.
• Specify that nextPageToken MUST NOT be included when hasNext is false.
• Add terminal and non-terminal pagination examples.

pageToken continuation semantics (#251)

• Clarify that pageToken is opaque and MUST be copied verbatim from a previous nextPageToken.
• Specify that clients MUST NOT parse, construct, or modify pageToken.
• Define continuation state, including:
  • pageSize
  • sortField
  • sortOrder
  • result-affecting filters such as idType and idValue
  • request path and path parameters such as parent uuid
• Specify that clients MUST NOT change result-affecting parameters while using a continuation token.
• Specify that servers MUST return 400 Bad Request for malformed, invalid, expired, conflicting, wrong-path, or wrong-path-parameter tokens.

Closes #249
Closes #250
Closes #251

[taleodor]

Great points, just want to request one change to exclude pageSize from the token scope.

[taleodor]

I would suggest excluding pageSize from this list, since that is not affecting results, and can be left to clients.

[Mehrn0ush]

Thanks, that makes sense. I updated the pageToken description to remove pageSize from the continuation state. The token scope now remains limited to sorting, result-affecting filters, and path/path-parameter scope.