Spec for MSC3981 (#1746)

* Spec for MSC3981

This writes up https://github.com/matrix-org/matrix-spec-proposals/pull/3981

Hopefully this is relatively straightforward, apart from having to add
the parameters and response field in all three places. I tried to factor
these out but it seems references just aren't supported in the right
places currently (see https://github.com/matrix-org/matrix-spec/pull/1745
for my efforts). Path parameters can't be optional, so it can't be done
that way either.

* Missed schemas

* newsfile

* Actually it clearly isn't going to support markdown, is it?

* grammar

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* grammar

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Clarity

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Clarity

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Typo

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* More clarity.

Note this is counter what the MSC actually proposed to add, but
I think it's clear that this is what it meant.

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

data/api/client-server/relations.yaml

@@ -1,4 +1,4 @@
-# Copyright 2022 The Matrix.org Foundation C.I.C.
+# Copyright 2022,2024 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -39,6 +39,7 @@ paths:
         - $ref: '#/components/parameters/to'
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/dir'
+        - $ref: '#/components/parameters/recurse'
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -96,6 +97,7 @@ paths:
         - $ref: '#/components/parameters/to'
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/dir'
+        - $ref: '#/components/parameters/recurse'
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -167,6 +169,7 @@ paths:
         - $ref: '#/components/parameters/to'
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/dir'
+        - $ref: '#/components/parameters/recurse'
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -294,6 +297,27 @@ components:
       example: org.example.my_relation
       schema:
         type: string
+    recurse:
+      in: query
+      name: recurse
+      x-addedInMatrixVersion: "1.10"
+      required: false
+      description: |-
+        Whether to additionally include events which only relate indirectly to the
+        given event, i.e. events related to the given event via two or more direct relationships.
+
+        If set to `false`, only events which have direct a relation with the given
+        event will be included.
+
+        If set to `true`, all events which relate to the given event, or relate to
+        events that relate to the given event, will be included.
+
+        It is recommended that homeservers traverse at least 3 levels of relationships.
+        Implementations may perform more but should be careful to not infinitely recurse.
+
+        The default value is `false`.
+      schema:
+        type: boolean
   schemas:
     response:
       type: object
@@ -308,6 +332,12 @@ components:
           description: |-
             An opaque string representing a pagination token. The absence of this token
             means this is the start of the result set, i.e. this is the first batch/page.
+        recursion_depth:
+          type: integer
+          description: |-
+            If the `recurse` parameter was supplied by the client, this response field is
+            mandatory and gives the actual depth to which the server recursed. If the client
+            did not specify the `recurse` parameter, this field must be absent.
   responses:
     "404":
       description: |-