Document group and context response keys

api/client-server/v1/search.yaml

@@ -161,15 +161,92 @@ paths:
                                 this result matches the search. Higher is
                                 closer.
                             result:
-                                type: object
-                                title: Event
-                                description: The event that matched.
-                                allOf:
-                                  - "$ref": "core-event-schema/room_event.json"
+                              type: object
+                              title: Event
+                              description: The event that matched.
+                              allOf:
+                                - "$ref": "core-event-schema/room_event.json"
+                            context:
+                              type: object
+                              title: Event Context
+                              description: Context for result, if requested.
+                              properties:
+                                start:
+                                  type: string
+                                  title: Start Token
+                                  description: |-
+                                    Pagination token for the start of the chunk
+                                end:
+                                  type: string
+                                  title: End Token
+                                  description: |-
+                                    Pagination token for the end of the chunk
+                                events_before:
+                                  type: array
+                                  title: Events Before
+                                  description: Events just before the result.
+                                  items:
+                                    type: object
+                                    title: Event
+                                    allOf:
+                                      - "$ref": "core-event-schema/room_event.json"
+                                events_after:
+                                  type: array
+                                  title: Events After
+                                  descriptions: Events just after the result.
+                                  items:
+                                    type: object
+                                    title: Event
+                                    allOf:
+                                      - "$ref": "core-event-schema/room_event.json"
+                      groups:
+                        type: object
+                        title: Groups
+                        description: Any groups that were requseted.
+                        additionalProperties:
+                          type: object
+                          title: Group Key
+                          description: The results for a given group.
+                          additionalProperties:
+                            type: object
+                            title: Group Value
+                            description: |-
+                                The results for a particular group value.
+                            properties:
+                              next_batch:
+                                type: string
+                                title: Next Batch in Group
+                                description: |-
+                                  Token that can be used to get the next
+                                  batch of results if exists.
+                              order:
+                                type: integer
+                                title: Group Order
+                                description: |-
+                                  Key that can be used to order different
+                                  groups.
+                              results:
+                                type: array
+                                description: |-
+                                  Which results are in this group.
+                                items:
+                                  type: string
+                                  title: Result Event ID
           examples:
             application/json: |-
                {
                   "search_categories": {
+                    "groups": {
+                      "room_id": {
+                        "!qPewotXpIctQySfjSy:localhost": {
+                          "order": 1,
+                          "next_batch": "BdgFsdfHSf-dsFD",
+                          "results": [
+                            "$144429830826TWwbB:localhost"
+                          ]
+                        }
+                      }
+                    },
                     "room_events": {
                       "count": 24,
                       "results": {
@@ -178,7 +255,7 @@ paths:
                           "result": {
                             "age": 526228296,
                             "content": {
-                              "body": "Test content",
+                              "body": "Test content martians and men",
                               "msgtype": "m.text"
                             },
                             "event_id": "$144429830826TWwbB:localhost",