incorporate feedback from reviewers

api/client-server/wellknown.yaml

@@ -27,14 +27,13 @@ paths:
       summary: Gets Matrix server discovery information about the domain.
       description: |-
         Gets discovery information about the domain.  The file may include
-        additional keys, which SHOULD follow the Java package naming convention,
+        additional keys, which MUST follow the Java package naming convention,
         e.g. ``com.example.myapp.property``. This ensures property names are
         suitably namespaced for each application and reduces the risk of
         clashes.
 
-        **FIXME:** do we need to add a note that this endpoint is not
-        necessarily handled by the homeserver, but by another webserver?  Or
-        does the context make this clear enough?
+        Note that this endpoint is not necessarily handled by the homeserver,
+        but by another webserver, to be used for discovering the homeserver URL.
       operationId: getWellknown
       responses:
         200:
@@ -55,8 +54,12 @@ paths:
                 description: Information about the homeserver to connect to.
                 "$ref": "definitions/wellknown/homeserver.yaml"
               m.identity_server:
-                description: Information about the identity server to connect to.
+                description: Optional. Information about the identity server to connect to.
                 "$ref": "definitions/wellknown/identity_server.yaml"
+            additionalProperties:
+              description: Application-dependent keys using Java package naming convention.
+            required:
+              - m.homeserver
         404:
           description: No server discovery information available
       tags:

changelogs/client_server.rst

@@ -16,6 +16,10 @@ Unreleased changes
     - Add sticker message event definition.
     (`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
 
+  - Server discovery:
+    - Add ``.well-known`` discovery method
+      (`#1359 <https://github.com/matrix-org/matrix-doc/pull/1359>`_).
+
 - Spec clarifications:
 
   - Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions

specification/client_server_api.rst

@@ -168,17 +168,17 @@ Server Discovery
 ~~~~~~~~~~~~~~~~
 
 In order to allow users to connect to a Matrix server without needing to
-explicitly specify the homeserver's URL or other parameters, clients may use an
-auto-discovery mechanism to determine the server's URL based on a user's
-Matrix ID. Auto-discovery should only be done at login time, with the
-discovered values retained for the duration of the user's session.
+explicitly specify the homeserver's URL or other parameters, clients SHOULD use
+an auto-discovery mechanism to determine the server's URL based on a user's
+Matrix ID. Auto-discovery should only be done at login time.
 
 In this section, the following terms are used with specific meanings:
 
 ``PROMPT``
   Retrieve the specific piece of information from the user in a way which
-  fits within the existing client UX, if the client is inclined to do so.
-  Failure can take place instead if no good UX is possible at this point.
+  fits within the existing client user experience, if the client is inclined to
+  do so. Failure can take place instead if no good user experience for this is
+  possible at this point.
 
 ``IGNORE``
   Stop the current auto-discovery mechanism. If no more auto-discovery
@@ -223,16 +223,19 @@ specify parameter values.  The flow for this method is as follows:
    e. Validate the homeserver base URL:
 
       i. Parse it as a URL.  If it is not a URL, then ``FAIL_ERROR``.
-      ii. Clients should validate that the URL points to a valid homeserver
-          before accepting it.  Currently, the suggested way of validating is
-          to connect to the ``/_matrix/client/versions`` endpoint, and to parse
-          and validate the data.  If any step in the validation fails, then
-          ``FAIL_ERROR``.
+      ii. Clients SHOULD validate that the URL points to a valid homeserver
+          before accepting it by connecting to the ``/_matrix/client/versions``
+          endpoint, and parsing and validating the data.  If any step in the
+          validation fails, then ``FAIL_ERROR``. Validation is done as a simple
+          check against configuration errors, before sending sensitive
+          information such as a user's password to the server.
 
    f. If the ``m.identity_server`` property is present, extract the
-      ``base_url`` value for use as the base URL of the identity server.  This
-      value can be validated as in the step above, but using
-      ``/_matrix/identity/api/v1``.
+      ``base_url`` value for use as the base URL of the identity server.
+      Validation for this URL is done as in the step above, but using
+      ``/_matrix/identity/api/v1`` as the endpoint to connect to.  If the
+      ``m.identity_server`` property is present, but does not have a
+      ``base_url`` value, then ``FAIL_ERROR``.
 
 {{wellknown_cs_http_api}}