From 1916e53f8cd4c94f18c721662e0547ecd1ca2e4c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Wed, 5 Mar 2025 10:56:49 +0100
Subject: [PATCH] Deduplicate `Invite3pid` (#2074)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Deduplicate Invite3pid

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/2074.clarification |  1 +
 data/api/client-server/create_room.yaml       | 27 +----------
 .../definitions/invite_3pid.yaml              | 45 +++++++++++++++++++
 .../client-server/third_party_membership.yaml | 32 +------------
 4 files changed, 48 insertions(+), 57 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/2074.clarification
 create mode 100644 data/api/client-server/definitions/invite_3pid.yaml

diff --git a/changelogs/internal/newsfragments/2074.clarification b/changelogs/internal/newsfragments/2074.clarification
new file mode 100644
index 00000000..4f941dd2
--- /dev/null
+++ b/changelogs/internal/newsfragments/2074.clarification
@@ -0,0 +1 @@
+Deduplicate the definitions of `Invite3pid`.
diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml
index 9e36d5e8..3992fdfe 100644
--- a/data/api/client-server/create_room.yaml
+++ b/data/api/client-server/create_room.yaml
@@ -131,32 +131,7 @@ paths:
                     A list of objects representing third-party IDs to invite into
                     the room.
                   items:
-                    type: object
-                    title: Invite3pid
-                    properties:
-                      id_server:
-                        type: string
-                        description: The hostname+port of the identity server which should be used for
-                          third-party identifier lookups.
-                      id_access_token:
-                        type: string
-                        description: |-
-                          An access token previously registered with the identity server. Servers
-                          can treat this as optional to distinguish between r0.5-compatible clients
-                          and this specification version.
-                      medium:
-                        type: string
-                        description: |-
-                          The kind of address being passed in the address field, for example `email`
-                          (see [the list of recognised values](/appendices/#3pid-types)).
-                      address:
-                        type: string
-                        description: The invitee's third-party identifier.
-                    required:
-                      - id_server
-                      - id_access_token
-                      - medium
-                      - address
+                    $ref: definitions/invite_3pid.yaml
                 room_version:
                   type: string
                   description: |-
diff --git a/data/api/client-server/definitions/invite_3pid.yaml b/data/api/client-server/definitions/invite_3pid.yaml
new file mode 100644
index 00000000..f00f15c5
--- /dev/null
+++ b/data/api/client-server/definitions/invite_3pid.yaml
@@ -0,0 +1,45 @@
+# Copyright 2025 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: Invite3pid
+properties:
+  id_server:
+    type: string
+    description: The hostname+port of the identity server which should be used for
+      third-party identifier lookups.
+  id_access_token:
+    type: string
+    description: |-
+      An access token previously registered with the identity server. Servers
+      can treat this as optional to distinguish between r0.5-compatible clients
+      and this specification version.
+  medium:
+    type: string
+    description: |-
+      The kind of address being passed in the address field, for example `email`
+      (see [the list of recognised values](/appendices/#3pid-types)).
+  address:
+    type: string
+    description: The invitee's third-party identifier.
+required:
+  - id_server
+  - id_access_token
+  - medium
+  - address
+example: {
+  "id_server": "matrix.org",
+  "id_access_token": "abc123_OpaqueString",
+  "medium": "email",
+  "address": "cheeky@monkey.com"
+}
\ No newline at end of file
diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml
index ea366648..65148ee0 100644
--- a/data/api/client-server/third_party_membership.yaml
+++ b/data/api/client-server/third_party_membership.yaml
@@ -76,37 +76,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              example: {
-                "id_server": "matrix.org",
-                "id_access_token": "abc123_OpaqueString",
-                "medium": "email",
-                "address": "cheeky@monkey.com"
-              }
-              properties:
-                id_server:
-                  type: string
-                  description: The hostname+port of the identity server which should be used for
-                    third-party identifier lookups.
-                id_access_token:
-                  type: string
-                  description: |-
-                    An access token previously registered with the identity server. Servers
-                    can treat this as optional to distinguish between r0.5-compatible clients
-                    and this specification version.
-                medium:
-                  type: string
-                  description: |-
-                    The kind of address being passed in the address field, for example
-                    `email` (see [the list of recognised values](/appendices/#3pid-types)).
-                address:
-                  type: string
-                  description: The invitee's third-party identifier.
-              required:
-                - id_server
-                - id_access_token
-                - medium
-                - address
+              $ref: definitions/invite_3pid.yaml
         required: true
       responses:
         "200":