Consolidate id_server into ref. id_server/next_link are ignored

api/client-server/administrative_contact.yaml

@@ -244,17 +244,7 @@ paths:
           name: body
           required: true
           schema:
-            allOf:
+            $ref: "../identity/definitions/request_email_validation.yaml"
-              - $ref: "../identity/definitions/request_email_validation.yaml"
-              - type: object
-                properties:
-                  id_server:
-                    type: string
-                    description: |-
-                      The hostname of the identity server to communicate with. May
-                      optionally include a port.
-                    example: "id.example.com"
-                required: ['id_server']
       responses:
         200:
           description: |-
@@ -305,17 +295,7 @@ paths:
           name: body
           required: true
           schema:
-            allOf:
+            $ref: "../identity/definitions/request_msisdn_validation.yaml"
-              - $ref: "../identity/definitions/request_msisdn_validation.yaml"
-              - type: object
-                properties:
-                  id_server:
-                    type: string
-                    description: |-
-                      The hostname of the identity server to communicate with. May
-                      optionally include a port.
-                    example: "id.example.com"
-                required: ['id_server']
       responses:
         200:
           description: An SMS message was sent to the given phone number.

api/identity/definitions/request_email_validation.yaml

@@ -45,7 +45,15 @@ properties:
   next_link:
     type: string
     description: |-
-      Optional. When the validation is completed, the identity
+      Optional. When the validation is completed, the identity server will
-      server will redirect the user to this URL.
+      redirect the user to this URL. This option is ignored when submitting
+      3PID validation information through a POST request.
     example: "https://example.org/congratulations.html"
-required: ["client_secret", "email", "send_attempt"]
+  id_server:
+    type: string
+    description: |-
+      The hostname of the identity server to communicate with. May optionally
+      include a port. This parameter is ignored when the homeserver handles
+      3PID verification.
+    example: "id.example.com"
+required: ["client_secret", "email", "send_attempt", "id_server"]

api/identity/definitions/request_msisdn_validation.yaml

@@ -51,7 +51,15 @@ properties:
   next_link:
     type: string
     description: |-
-      Optional. When the validation is completed, the identity
+      Optional. When the validation is completed, the identity server will
-      server will redirect the user to this URL.
+      redirect the user to this URL. This option is ignored when submitting
+      3PID validation information through a POST request.
     example: "https://example.org/congratulations.html"
-required: ["client_secret", "country", "phone_number", "send_attempt"]
+  id_server:
+    type: string
+    description: |-
+      The hostname of the identity server to communicate with. May optionally
+      include a port. This parameter is ignored when the homeserver handles
+      3PID verification.
+    example: "id.example.com"
+required: ["client_secret", "country", "phone_number", "send_attempt", "id_server"]