Add membership reasons to the spec for all membership events

MSC: https://github.com/matrix-org/matrix-doc/pull/2367

api/client-server/banning.yaml

@@ -61,7 +61,7 @@ paths:
                 description: The fully qualified user ID of the user being banned.
               reason:
                 type: string
-                description: The reason the user has been banned. This will be supplied as the 
+                description: The reason the user has been banned. This will be supplied as the
                   ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
@@ -111,12 +111,18 @@ paths:
           schema:
             type: object
             example: {
-                "user_id": "@cheeky_monkey:matrix.org"
-              }
+              "user_id": "@cheeky_monkey:matrix.org",
+              "reason": "They've been banned long enough"
+            }
             properties:
               user_id:
                 type: string
                 description: The fully qualified user ID of the user being unbanned.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
             required: ["user_id"]
       responses:
         200:

api/client-server/inviting.yaml

@@ -67,12 +67,18 @@ paths:
           schema:
             type: object
             example: {
-                "user_id": "@cheeky_monkey:matrix.org"
-              }
+              "user_id": "@cheeky_monkey:matrix.org",
+              "reason": "Welcome to the team!"
+            }
             properties:
               user_id:
                 type: string
                 description: The fully qualified user ID of the invitee.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
             required: ["user_id"]
       responses:
         200:

api/client-server/joining.yaml

@@ -52,7 +52,7 @@ paths:
           required: true
           x-example: "!d41d8cd:matrix.org"
         - in: body
-          name: third_party_signed
+          name: body
           required: true
           schema:
             type: object
@@ -64,6 +64,12 @@ paths:
                   If supplied, the homeserver must verify that it matches a pending
                   ``m.room.third_party_invite`` event in the room, and perform
                   key validity checking if required by the event.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
+                example: "Looking for support"
       responses:
         200:
           description: |-
@@ -131,7 +137,7 @@ paths:
             must be participating in the room.
           x-example: ["matrix.org", "elsewhere.ca"]
         - in: body
-          name: third_party_signed
+          name: body
           required: true
           schema:
             type: object
@@ -143,6 +149,12 @@ paths:
                   If a ``third_party_signed`` was supplied, the homeserver must verify
                   that it matches a pending ``m.room.third_party_invite`` event in the
                   room, and perform key validity checking if required by the event.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
+                example: "Looking for support"
       responses:
         200:
           description: |-

api/client-server/leaving.yaml

@@ -52,6 +52,20 @@ paths:
           description: The room identifier to leave.
           required: true
           x-example: "!nkl290a:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: {
+              "reason": "Saying farewell - thanks for the support!"
+            }
+            properties:
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
       responses:
         200:
           description: |-

event-schemas/examples/m.room.member

@@ -5,6 +5,7 @@
   "content": {
     "membership": "join",
     "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
-    "displayname": "Alice Margatroid"
+    "displayname": "Alice Margatroid",
+    "reason": "Looking for support"
   }
 }

event-schemas/examples/m.room.member$invite_room_state

@@ -3,7 +3,8 @@
   "content": {
     "membership": "invite",
     "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
-    "displayname": "Alice Margatroid"
+    "displayname": "Alice Margatroid",
+    "reason": "Looking for support"
   },
   "unsigned": {
     "age": 1234,

event-schemas/schema/m.room.member

@@ -67,6 +67,15 @@ properties:
       is_direct:
         description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See `Direct Messaging`_.
         type: boolean
+      reason:
+        type: string
+        description: |-
+          Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban.
+          For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such
+          as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day.
+
+          Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the
+          reason behind a button or other component is recommended.
       third_party_invite:
         properties:
           display_name: