Fix third party signed definitions for join APIs

Fixes https://github.com/matrix-org/matrix-doc/issues/1978

api/client-server/definitions/third_party_signed.yaml

@@ -0,0 +1,41 @@
+# Copyright 2019 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: Third Party Signed
+description: |-
+  A signature of an ``m.third_party_invite`` token to prove that this user
+  owns a third party identity which has been invited to the room.
+properties:
+  sender:
+    type: string
+    description: The Matrix ID of the user who issued the invite.
+    example: "@alice:example.org"
+  mxid:
+    type: string
+    description: The Matrix ID of the invitee.
+    example: "@bob:example.org"
+  token:
+    type: string
+    description: The state key of the m.third_party_invite event.
+    example: "random8nonce"
+  signatures:
+    type: object
+    description: A signatures object containing a signature of the entire signed object.
+    title: Signatures
+    example: {
+      "example.org": {
+        "ed25519:0": "some9signature"
+      }
+    }
+required: ["sender", "mxid", "token", "signatures"]

api/client-server/joining.yaml

@@ -58,38 +58,9 @@ paths:
           name: third_party_signed
           schema:
             type: object
-            example: {
-                "third_party_signed": {
-                  "sender": "@cat:the.hat",
-                  "mxid": "@green:eggs.ham",
-                  "token": "random8nonce",
-                  "signatures": {
-                    "horton.hears": {
-                      "ed25519:0": "some9signature"
-                    }
-                  }
-                }
-              }
             properties:
               third_party_signed:
-                type: object
-                title: ThirdPartySigned
-                description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
-                properties:
-                  sender:
-                    type: string
-                    description: The Matrix ID of the user who issued the invite.
-                  mxid:
-                    type: string
-                    description: The Matrix ID of the invitee.
-                  token:
-                    type: string
-                    description: The state key of the m.third_party_invite event.
-                  signatures:
-                    type: object
-                    description: A signatures object containing a signature of the entire signed object.
-                    title: Signatures
-                required: ["sender", "mxid", "token", "signatures"]
+                $ref: "definitions/third_party_signed.yaml"
       responses:
         200:
           description: |-
@@ -163,45 +134,9 @@ paths:
           name: third_party_signed
           schema:
             type: object
-            example: {
-                "third_party_signed": {
-                  "signed": {
-                    "sender": "@cat:the.hat",
-                    "mxid": "@green:eggs.ham",
-                    "token": "random8nonce",
-                    "signatures": {
-                      "horton.hears": {
-                        "ed25519:0": "some9signature"
-                      }
-                    }
-                  }
-                }
-              }
             properties:
               third_party_signed:
-                type: object
-                title: ThirdPartySigned
-                description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
-                properties:
-                  signed:
-                    type: object
-                    title: Signed
-                    properties:
-                      sender:
-                        type: string
-                        description: The Matrix ID of the user who issued the invite.
-                      mxid:
-                        type: string
-                        description: The Matrix ID of the invitee.
-                      token:
-                        type: string
-                        description: The state key of the m.third_party_invite event.
-                      signatures:
-                        type: object
-                        description: A signatures object containing a signature of the entire signed object.
-                        title: Signatures
-                    required: ["sender", "mxid", "token", "signatures"]
-                required: ["signed"]
+                $ref: "definitions/third_party_signed.yaml"
       responses:
         200:
           description: |-

specification/modules/third_party_invites.rst

@@ -38,7 +38,8 @@ When the invitee's homeserver receives the notification of the binding, it
 should insert an ``m.room.member`` event into the room's graph for that user,
 with ``content.membership`` = ``invite``, as well as a
 ``content.third_party_invite`` property which contains proof that the invitee
-does indeed own that third party identifier.
+does indeed own that third party identifier. See the `m.room.member <#m-room-member>`_
+schema for more information.
 
 
 Events