🎯 User Story
As a PDS Data User, I want to sort API results in ascending or descending order per field so that I can retrieve data in the order most useful for my query (e.g., newest first, oldest first, lowest version first).
✨ Motivation
The sort query parameter currently accepts one or more field names but unconditionally sorts all fields in ascending order. There is no way for a caller to request descending order for any field. This limits the usefulness of the sort feature — for example, a user cannot ask for the most recently harvested products first, or retrieve the highest version of a product at the top of results.
The current behavior is documented in the OpenAPI spec (swagger.yml) with the note: "currently only sorts ascending", confirming this is a known limitation rather than intended design.
📋 Proposed Change
Extend the sort parameter syntax to support an optional direction modifier per field. The proposed syntax aligns with common REST API conventions:
Where <direction> is either asc (default, backwards-compatible) or desc.
Examples:
sort=ops:Harvest_Info.ops:harvest_date_time:desc — most recently harvested firstsort=vid:asc — lowest version first (same as current default)sort=vid — ascending (no direction = default asc, fully backwards-compatible)sort=title:asc&sort=vid:desc — multi-field: title ascending, then version descending
Affected components:
swagger.yml — update the Sort parameter description to document the new syntaxRegistrySearchRequestBuilder.sortFromStrings() — parse the optional :asc/:desc suffix and pass SortOrder.Asc or SortOrder.Desc accordingly to the OpenSearch FieldSort- Unit tests in
RegistrySearchRequestBuilderTest — add coverage for ascending, descending, and default (no-direction) sort inputs
- Integration tests — add test cases exercising descending sort
🩺 Additional Context
- The
search-after pagination feature requires a matching sort list; the new syntax must not break the existing length-equality validation between sort and search-after.
- Backwards compatibility must be preserved: a bare field name with no
:asc/:desc suffix must continue to sort ascending.
- The field-name-to-OpenSearch-property conversion in
SearchUtil.jsonPropertyToOpenProperty() must occur on the field portion only, not on the direction suffix.
For Internal Dev Team To Complete
⚙️ Engineering Details
🎉 Integration & Test
🎯 User Story
As a PDS Data User, I want to sort API results in ascending or descending order per field so that I can retrieve data in the order most useful for my query (e.g., newest first, oldest first, lowest version first).
✨ Motivation
The
sortquery parameter currently accepts one or more field names but unconditionally sorts all fields in ascending order. There is no way for a caller to request descending order for any field. This limits the usefulness of the sort feature — for example, a user cannot ask for the most recently harvested products first, or retrieve the highest version of a product at the top of results.The current behavior is documented in the OpenAPI spec (
swagger.yml) with the note: "currently only sorts ascending", confirming this is a known limitation rather than intended design.📋 Proposed Change
Extend the
sortparameter syntax to support an optional direction modifier per field. The proposed syntax aligns with common REST API conventions:Where
<direction>is eitherasc(default, backwards-compatible) ordesc.Examples:
sort=ops:Harvest_Info.ops:harvest_date_time:desc— most recently harvested firstsort=vid:asc— lowest version first (same as current default)sort=vid— ascending (no direction = defaultasc, fully backwards-compatible)sort=title:asc&sort=vid:desc— multi-field: title ascending, then version descendingAffected components:
swagger.yml— update theSortparameter description to document the new syntaxRegistrySearchRequestBuilder.sortFromStrings()— parse the optional:asc/:descsuffix and passSortOrder.AscorSortOrder.Descaccordingly to the OpenSearchFieldSortRegistrySearchRequestBuilderTest— add coverage for ascending, descending, and default (no-direction) sort inputs🩺 Additional Context
search-afterpagination feature requires a matching sort list; the new syntax must not break the existing length-equality validation betweensortandsearch-after.:asc/:descsuffix must continue to sort ascending.SearchUtil.jsonPropertyToOpenProperty()must occur on the field portion only, not on the direction suffix.For Internal Dev Team To Complete
⚙️ Engineering Details
🎉 Integration & Test