Add changelog, update imperative check, rename sid.yaml

api/client-server/administrative_contact.yaml

@@ -135,7 +135,7 @@ paths:
           description: The addition was successful.
           examples:
             application/json: {
-                "submit_url": "https://example.org/path/to/submitToken"
+              "submit_url": "https://example.org/path/to/submitToken"
             }
             schema:
               type: object
@@ -235,7 +235,9 @@ paths:
         the |/register/email/requestToken|_ endpoint. The homeserver has the
         choice of validating the email address itself, or proxying the request
         to the ``/validate/email/requestToken`` Identity Service API as
-        identified by ``id_server``.
+        identified by ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
       operationId: requestTokenTo3PIDEmail
       parameters:
         - in: body
@@ -260,7 +262,7 @@ paths:
             email containing the validation token or it may be informing the
             user of an error.
           schema:
-            $ref: "definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: |-
             The homeserver does not allow the third party identifier as a
@@ -294,7 +296,9 @@ paths:
         the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
         choice of validating the phone number itself, or proxying the request
         to the ``/validate/msisdn/requestToken`` Identity Service API as
-        identified by ``id_server``.
+        identified by ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
       operationId: requestTokenTo3PIDMSISDN
       parameters:
         - in: body
@@ -316,7 +320,7 @@ paths:
         200:
           description: An SMS message was sent to the given phone number.
           schema:
-            $ref: "definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: |-
             The homeserver does not allow the third party identifier as a

api/client-server/registration.yaml

@@ -241,7 +241,7 @@ paths:
             may be an email containing the validation token or it may be
             informing the user of an error.
           schema:
-            $ref: "definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: The homeserver does not permit the address to be bound.
           schema:
@@ -304,7 +304,7 @@ paths:
             that this may be an SMS message containing the validation token or
             it may be informing the user of an error.
           schema:
-            $ref: "definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: The homeserver does not permit the address to be bound.
           schema:
@@ -402,11 +402,11 @@ paths:
         ``M_THREEPID_IN_USE`` may not be returned.
         
         The homeserver has the choice of validating the email address itself,
-        or proxying the request to the ``/validate/email/requestToken`` Identity
+        or proxying the request to the ``/validate/email/requestToken``
-        Server API. The request should be proxied to the domain that is sent by
+        Identity Service API. The request should be proxied to the domain that
-        the client in the ``id_server``. It is imperative that the homeserver
+        is sent by the client in the ``id_server``. It is imperative that the
-        keep a list of trusted Identity Servers and only proxies to those it
+        homeserver keep a list of trusted Identity Servers and only proxies to
-        trusts.
+        those that it trusts.
 
 
         .. |/register/email/requestToken| replace:: ``/register/email/requestToken``
@@ -433,7 +433,7 @@ paths:
         200:
           description: An email was sent to the given address.
           schema:
-            $ref: "definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: |-
             The homeserver does not allow the third party identifier as a
@@ -472,12 +472,12 @@ paths:
         to the given phone number prompting the user to create an account.
         ``M_THREEPID_IN_USE`` may not be returned.
         
-        The homeserver has the choice of validating the phone number itself,
+        The homeserver has the choice of validating the phone number itself, or
-        or proxying the request to the ``/validate/msisdn/requestToken`` Identity
+        proxying the request to the ``/validate/msisdn/requestToken`` Identity
-        Server API. The request should be proxied to the domain that is sent by
+        Service API. The request should be proxied to the domain that is sent
-        the client in the ``id_server``. It is imperative that the homeserver
+        by the client in the ``id_server``. It is imperative that the
-        keep a list of trusted Identity Servers and only proxies to those it
+        homeserver keep a list of trusted Identity Servers and only proxies to
-        trusts.
+        those that it trusts.
 
         .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
 
@@ -503,7 +503,7 @@ paths:
         200:
           description: An SMS message was sent to the given phone number.
           schema:
-            $ref: "definitions/sid.yaml"
+            $ref: "definitions/request_token_response.yaml"
         403:
           description: |-
             The homeserver does not allow the third party identifier as a

changelogs/client_server/newsfragments/2101.breaking

@@ -0,0 +1 @@
+Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints.