From 13117f315c265043de9de5c89f95b03f80b33fdc 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 5c22847..ae0aea8 100644
--- a/api/openapi-spec/v1.0.yaml
+++ b/api/openapi-spec/v1.0.yaml
@@ -6574,6 +6574,41 @@ components:
             `invalidRequest`.
           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: |