Merge remote-tracking branch 'remotes/origin/master'

api/README

@@ -1,3 +1,2 @@
 This directory contains swagger-compatible representations of our APIs. See
-scripts/README.md for details on how to make use of them.
-
+the main README.rst for details on how to make use of them.

api/client-server/create_room.yaml

@@ -37,6 +37,9 @@ paths:
         the new room, including checking power levels for each event. It MUST
         apply the events implied by the request in the following order:
 
+        0. A default ``m.room.power_levels`` event, giving the room creator
+           (and not other members) permission to send state events.
+        
         1. Events set by ``presets``.
 
         2. Events listed in ``initial_state``, in the order that they are

api/client-server/definitions/event.yaml

@@ -12,6 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 properties:
+  event_id:
+    description: The ID of this event, if applicable.
+    type: string
   content:
     description: The content of this event. The fields in this object will vary depending
       on the type of event.

api/client-server/filter.yaml

@@ -149,5 +149,7 @@ paths:
             type: object
             allOf:
               - $ref: "definitions/sync_filter.yaml"
+        404:
+          description: "Unknown filter."
       tags:
         - Room participation

api/client-server/registration.yaml

@@ -45,6 +45,16 @@ paths:
         If the client does not supply a ``device_id``, the server must
         auto-generate one.
 
+        The server SHOULD register an account with a User ID based on the
+        ``username`` provided, if any. Note that the grammar of Matrix User ID
+        localparts is restricted, so the server MUST either map the provided
+        ``username`` onto a ``user_id`` in a logical manner, or reject
+        ``username``\s which do not comply to the grammar, with
+        ``M_INVALID_USERNAME``.
+
+        Matrix clients MUST NOT assume that localpart of the registered
+        ``user_id`` matches the provided ``username``.
+
         The returned access token must be associated with the ``device_id``
         supplied by the client or generated by the server. The server may
         invalidate any access token previously associated with that device. See
@@ -87,7 +97,7 @@ paths:
               username:
                 type: string
                 description: |-
-                  The local part of the desired Matrix ID. If omitted,
+                  The basis for the localpart of the desired Matrix ID. If omitted,
                   the homeserver MUST generate a Matrix ID local part.
                 example: cheeky_monkey
               password:
@@ -122,7 +132,11 @@ paths:
             properties:
               user_id:
                 type: string
-                description: The fully-qualified Matrix ID that has been registered.
+                description: |-
+                  The fully-qualified Matrix user ID (MXID) that has been registered.
+
+                  Any user ID returned by this API must conform to the grammar given in the
+                  `Matrix specification <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_.
               access_token:
                 type: string
                 description: |-

api/client-server/search.yaml

@@ -89,8 +89,12 @@ paths:
                       filter:
                         type: object
                         title: Filter
+                        # Within the C-S spec document, `filter`_ is picked up
+                        # as a link to the filtering section. In OpenAPI 3.0,
+                        # we could use the link feature, but we're still on 2.0
+                        # for now :/
                         description: |-
-                          This takes a `filter <https://matrix.org/docs/spec/%CLIENT_RELEASE_LABEL%/client_server.html#filtering>`_.
+                          This takes a `filter`_.
                       order_by:
                         title: "Ordering"
                         type: string