From c400b397ed8b63dbd71bd0083ac0f04c4140216f Mon Sep 17 00:00:00 2001
From: Dominik Schmidt <dev@dominik-schmidt.de>
Date: Thu, 13 Aug 2026 00:41:11 +0200
Subject: [PATCH] feat(search): sortProperties on searchRequest

Adds `sortProperties` to searchRequest, following the MS Graph
sortProperty resource type: an ordered list of {name, isDescending}
entries; results are sorted by relevance when absent.

Sortable are the scalar properties carried on the search hit's
resource (name, size, lastModifiedDateTime, mimeType and scalar facet
properties such as photo.takenDateTime or audio.artist). Strings sort
lexicographically, numbers and dates by value. Multivalued and
unknown properties are rejected with invalidRequest.
---
 api/openapi-spec/v1.0.yaml | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/api/openapi-spec/v1.0.yaml b/api/openapi-spec/v1.0.yaml
index d85ee65..a771585 100644
--- a/api/openapi-spec/v1.0.yaml
+++ b/api/openapi-spec/v1.0.yaml
@@ -5962,6 +5962,41 @@ components:
             results in a logical AND between the filters.
           items:
             type: string
+        sortProperties:
+          type: array
+          description: |
+            Contains the ordered collection of fields to sort the results on.
+            If absent, the results are sorted by relevance. See
+            `sortProperty.name` for the set of sortable fields. Optional.
+          items:
+            $ref: '#/components/schemas/sortProperty'
+    sortProperty:
+      type: object
+      description: |
+        Indicates the order to sort search results in. Follows the
+        [MS Graph sortProperty](https://learn.microsoft.com/en-us/graph/api/resources/sortproperty)
+        resource type.
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the property to sort the search results by. Required.
+
+            Sortable are the scalar properties carried on the search hit's
+            resource: `name`, `size`, `lastModifiedDateTime`, `mimeType` and
+            the scalar facet properties such as `photo.takenDateTime`,
+            `photo.iso`, `audio.artist`, `audio.year` or `image.width`.
+            Strings sort lexicographically, numbers and dates by value.
+            Multivalued properties (e.g. `tags`) and unknown properties are
+            rejected with `invalidRequest`.
+        isDescending:
+          type: boolean
+          description: |
+            Set to `true` to sort the results in descending order. Optional,
+            defaults to `false` (ascending).
+          default: false
     searchQuery:
       type: object
       description: |