From 4ff5887c917b3595344f01d33b134a1658a1e4a1 Mon Sep 17 00:00:00 2001
From: Michael Telatynski <7t3chguy@gmail.com>
Date: Tue, 5 Jun 2018 10:06:26 +0100
Subject: [PATCH 1/4] spec the highlights field in /search response

---
 api/client-server/search.yaml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index c4f38fa1..7c5a9a5b 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -181,6 +181,12 @@ paths:
                       count:
                         type: number
                         description: An approximate count of the total number of results found.
+                      highlights:
+                        type: array
+                        title: Highlights
+                        description: List of words which should be highlighted, useful for stemming which may change the query terms.
+                        items:
+                          type: string
                       results:
                         type: array
                         title: Results

From 64f97c5b7861b84bd53993214c89db6dff97862b Mon Sep 17 00:00:00 2001
From: Michael Telatynski <7t3chguy@gmail.com>
Date: Tue, 5 Jun 2018 10:10:24 +0100
Subject: [PATCH 2/4] add example of highlights field in /search response

---
 api/client-server/search.yaml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index 7c5a9a5b..65730e38 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -324,6 +324,10 @@ paths:
                           }
                         }
                       },
+                      "highlights": [
+                        "martians",
+                        "men"
+                      ],
                       "next_batch": "5FdgFsd234dfgsdfFD",
                       "count": 1224,
                       "results": [

From df5455de1f993104c772f85af6f115ec0751a3d1 Mon Sep 17 00:00:00 2001
From: Michael Telatynski <7t3chguy@gmail.com>
Date: Tue, 5 Jun 2018 10:12:34 +0100
Subject: [PATCH 3/4] re-arrange fields in example /search request to make them
 a valid request.

---
 api/client-server/search.yaml | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index 65730e38..e5f6a872 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -53,16 +53,16 @@ paths:
                     "keys": [
                       "content.body"
                     ],
-                    "search_term": "martians and men"
-                  }
-                },
-                "order_by": "recent",
-                "groupings": {
-                  "group_by": [
-                    {
-                      "key": "room_id"
+                    "search_term": "martians and men",
+                    "order_by": "recent",
+                    "groupings": {
+                      "group_by": [
+                        {
+                          "key": "room_id"
+                        }
+                      ]
                     }
-                  ]
+                  }
                 }
               }
             properties:

From 968ee0f61379b5c021ef26044ba59e566906014e Mon Sep 17 00:00:00 2001
From: Michael Telatynski <7t3chguy@gmail.com>
Date: Tue, 5 Jun 2018 10:13:54 +0100
Subject: [PATCH 4/4] add changelog

---
 changelogs/client_server.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst
index 92d13103..24344116 100644
--- a/changelogs/client_server.rst
+++ b/changelogs/client_server.rst
@@ -54,6 +54,8 @@ Unreleased changes
     (`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
   - Document ``/logout/all`` endpoint
     (`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
+  - Document `highlights` field in /search response
+    (`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
 
 r0.3.0
 ======