Merge remote matrix-org/master

.circleci/config.yml

@@ -23,9 +23,55 @@ buildswaggerui: &buildswaggerui
     wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/swagger-ui.patch
     patch api/client-server/index.html swagger-ui.patch
 
+checkexamples: &checkexamples
+  name: Check Event Examples
+  command: |
+    source /env/bin/activate
+    cd event-schemas
+    ./check_examples.py
+    cd ../api
+    ./check_examples.py
+
+genmatrixassets: &genmatrixassets
+  name: Generate/Verify matrix.org assets
+  command: |
+    source /env/bin/activate
+    ./scripts/generate-matrix-org-assets
+
+validateapi: &validateapi
+  name: Validate OpenAPI specifications
+  command: |
+    cd api
+    npm install
+    node validator.js -s "client-server"
+
+buildspeculator: &buildspeculator
+  name: Build Speculator
+  command: |
+    cd scripts/speculator
+    go build -v
+
+buildcontinuserv: &buildcontinuserv
+  name: Build Continuserv
+  command: |
+    cd scripts/continuserv
+    go build -v
 
 version: 2
 jobs:
+  validate-docs:
+    docker:
+      - image: node:alpine
+    steps:
+      - checkout
+      - run: *validateapi
+  check-docs:
+    docker:
+      - image: uhoreg/matrix-doc-build
+    steps:
+      - checkout
+      - run: *checkexamples
+      - run: *genmatrixassets # We don't actually use the assets, but we do want to make sure they build
   build-docs:
     docker:
       - image: uhoreg/matrix-doc-build
@@ -37,7 +83,6 @@ jobs:
       - run:
           name: "Doc build is available at:"
           command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/gen/index.html"; echo $DOCS_URL
-
   build-swagger:
     docker:
       - image: uhoreg/matrix-doc-build
@@ -50,6 +95,18 @@ jobs:
       - run:
           name: "Swagger UI is available at:"
           command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL
+  build-dev-scripts:
+    docker:
+      - image: golang:1.8
+    steps:
+      - checkout
+      - run:
+          name: Install Dependencies
+          command: |
+            go get -v github.com/hashicorp/golang-lru
+            go get -v gopkg.in/fsnotify/fsnotify.v1
+      - run: *buildcontinuserv
+      - run: *buildspeculator
 
 workflows:
   version: 2
@@ -58,6 +115,9 @@ workflows:
     jobs:
       - build-docs
       - build-swagger
+      - check-docs
+      - validate-docs
+      - build-dev-scripts
 
 notify:
   webhooks:

api/application-service/definitions/location.yaml

@@ -19,12 +19,14 @@ properties:
   protocol:
     description: The protocol ID that the third party location is a part of.
     type: string
-    example: irc
+    example: "irc"
   fields:
     description: Information used to identify this third party location.
     type: object
-    example:
+    example: {
-      "network": "freenode"
+      "network": "freenode",
       "channel": "#matrix"
+    }
+required: ['alias', 'protocol', 'fields']
 title: Location
 type: object

api/application-service/definitions/protocol.yaml

@@ -11,41 +11,60 @@
 # 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.
+title: Protocol
+type: object
 properties:
   user_fields:
-    description: Fields used to identify a third party user.
+    description: |-
+      Fields which may be used to identify a third party user. These should be
+      ordered to suggest the way that entities may be grouped, where higher
+      groupings are ordered first. For example, the name of a network should be
+      searched before the nickname of a user.
     type: array
     items:
       type: string
       description: Field used to identify a third party user.
     example: ["network", "nickname"]
   location_fields:
-    description: Fields used to identify a third party location.
+    description: |-
+      Fields which may be used to identify a third party location. These should be
+      ordered to suggest the way that entities may be grouped, where higher
+      groupings are ordered first. For example, the name of a network should be
+      searched before the name of a channel.
     type: array
     items:
       type: string
       description: Field used to identify a third party location.
     example: ["network", "channel"]
   icon:
-    description: An icon representing the third party protocol.
+    description: A content URI representing an icon for the third party protocol.
     type: string
     example: "mxc://example.org/aBcDeFgH"
   field_types:
     title: Field Types
-    description: All location or user fields should have an entry here.
+    description: |-
+      The type definitions for the fields defined in the ``user_fields`` and 
+      ``location_fields``. Each entry in those arrays MUST have an entry here. The
+      ``string`` key for this object is field name itself.
+
+      May be an empty object if no fields are defined.
     type: object
-    properties:
+    additionalProperties:
-      fieldname:
+      title: Field Type
-        title: Field Type
+      description: Definition of valid values for a field.
-        description: Definition of valid values for a field.
+      type: object
-        type: object
+      properties:
-        properties:
+        regexp:
-          regexp:
+          description: |-
-            description: A regular expression for validation of a field's value.
+            A regular expression for validation of a field's value. This may be relatively
-            type: string
+            coarse to verify the value as the application service providing this protocol
-          placeholder:
+            may apply additional validation or filtering.
-            description: An placeholder serving as a valid example of the field value.
+          type: string
-            type: string
+        placeholder:
+          description: An placeholder serving as a valid example of the field value.
+          type: string
+      required: ['regexp', 'placeholder']
+    required: ['fieldname']
     example: {
       "network": {
         "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
@@ -63,17 +82,32 @@ properties:
   instances:
     description: |-
       A list of objects representing independent instances of configuration.
-      For instance multiple networks on IRC if multiple are bridged by the
+      For example, multiple networks on IRC if multiple are provided by the
-      same bridge.
+      same application service.
     type: array
     items:
       type: object
-      example: {
+      title: Protocol Instance
-        "desc": "Freenode",
+      properties:
-        "icon": "mxc://example.org/JkLmNoPq",
+        desc:
-        "fields": {
+          type: string
-          "network": "freenode.net",
+          description: A human-readable description for the protocol, such as the name.
-        }
+          example: "Freenode"
-      }
+        icon:
-title: Protocol
+          type: string
-type: object
+          description: |-
+            An optional content URI representing the protocol. Overrides the one provided
+            at the higher level Protocol object.
+          example: "mxc://example.org/JkLmNoPq"
+        fields:
+          type: object
+          description: Preset values for ``fields`` the client may use to search by.
+          example: {
+            "network": "freenode"
+          }
+        network_id:
+          type: string
+          description: A unique identifier across all instances.
+          example: "freenode"
+      required: ['desc', 'fields', 'network_id']
+required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

api/application-service/definitions/protocol_metadata.yaml

@@ -36,6 +36,7 @@ example: {
     },
     "instances": [
       {
+        "network_id": "freenode",
         "desc": "Freenode",
         "icon": "mxc://example.org/JkLmNoPq",
         "fields": {
@@ -59,6 +60,7 @@ example: {
     },
     "instances": [
       {
+        "network_id": "gitter",
         "desc": "Gitter",
         "icon": "mxc://example.org/zXyWvUt",
         "fields": {}

api/application-service/definitions/security.yaml

@@ -0,0 +1,18 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+homeserverAccessToken:
+  type: apiKey
+  description: The ``hs_token`` provided by the application service's registration.
+  name: access_token
+  in: query

api/application-service/definitions/user.yaml

@@ -21,11 +21,13 @@ properties:
   protocol:
     description: The protocol ID that the third party location is a part of.
     type: string
-    example: gitter
+    example: "gitter"
   fields:
     description: Information used to identify this third party location.
     type: object
-    example:
+    example: {
       "user": "jim"
+    }
+required: ['userid', 'protocol', 'fields']
 title: User
 type: object

api/application-service/protocols.yaml

@@ -1,4 +1,3 @@
-# Copyright 2016 OpenMarket Ltd
 # Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -20,83 +19,15 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: "/"
+basePath: /_matrix/app/v1
 consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
-  "/transactions/{txnId}":
+  "/thirdparty/protocol/{protocol}":
-    put:
-      summary: Send some events to the application service.
-      description: |-
-        This API is called by the homeserver when it wants to push an event
-        (or batch of events) to the application service.
-
-        Note that the application service should distinguish state events
-        from message events via the presence of a ``state_key``, rather than
-        via the event type.
-      operationId: sendTransaction
-      parameters:
-        - in: path
-          name: txnId
-          type: string
-          description: |-
-            The transaction ID for this set of events. Homeservers generate
-            these IDs and they are used to ensure idempotency of requests.
-          required: true
-          x-example: "35"
-        - in: body
-          name: body
-          description: A list of events.
-          schema:
-            type: object
-            example: {
-              "events": [
-                {
-                  "age": 32,
-                  "content": {
-                      "body": "incoming message",
-                      "msgtype": "m.text"
-                  },
-                  "event_id": "$14328055551tzaee:localhost",
-                  "origin_server_ts": 1432804485886,
-                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                  "type": "m.room.message",
-                  "user_id": "@bob:localhost"
-                },
-                {
-                  "age": 1984,
-                  "content": {
-                      "body": "another incoming message",
-                      "msgtype": "m.text"
-                  },
-                  "event_id": "$1228055551ffsef:localhost",
-                  "origin_server_ts": 1432804485886,
-                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                  "type": "m.room.message",
-                  "user_id": "@bob:localhost"
-                }
-              ]
-            }
-            description: "Transaction informations"
-            properties:
-              events:
-                type: array
-                description: A list of events
-                items:
-                  type: object
-                  title: Event
-            required: ["events"]
-      responses:
-        200:
-          description: The transaction was processed successfully.
-          examples:
-            application/json: {
-            }
-          schema:
-            type: object
-  "/_matrix/app/unstable/thirdparty/protocol/{protocol}":
     get:
       summary: Retrieve metadata about a specific protocol that the application service supports.
       description: |-
@@ -104,6 +35,8 @@ paths:
         with specific information about the various third party networks that
         an application service supports.
       operationId: getProtocolMetadata
+      security:
+        - homeserverAccessToken: []
       parameters:
         - in: path
           name: protocol
@@ -143,7 +76,7 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/user/{protocol}":
+  "/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third party user.
       description: |-
@@ -151,6 +84,8 @@ paths:
         User ID linked to a user on the third party network, given a set of
         user parameters.
       operationId: queryUserByProtocol
+      security:
+        - homeserverAccessToken: []
       parameters:
         - in: path
           name: protocol
@@ -196,12 +131,14 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/location/{protocol}":
+  "/thirdparty/location/{protocol}":
     get:
-      summary: Retreive Matrix-side portal rooms leading to a third party location.
+      summary: Retrieve Matrix-side portal rooms leading to a third party location.
       description: |-
         Retrieve a list of Matrix portal rooms that lead to the matched third party location.
       operationId: queryLocationByProtocol
+      security:
+        - homeserverAccessToken: []
       parameters:
         - in: path
           name: protocol
@@ -247,13 +184,15 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/location":
+  "/thirdparty/location":
     get:
       summary: Reverse-lookup third party locations given a Matrix room alias.
       description: |-
-        Retreive an array of third party network locations from a Matrix room
+        Retrieve an array of third party network locations from a Matrix room
         alias.
       operationId: queryLocationByAlias
+      security:
+        - homeserverAccessToken: []
       parameters:
         - in: query
           name: alias
@@ -292,12 +231,14 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/user":
+  "/thirdparty/user":
     get:
       summary: Reverse-lookup third party users given a Matrix User ID.
       description: |-
-        Retreive an array of third party users from a Matrix User ID.
+        Retrieve an array of third party users from a Matrix User ID.
       operationId: queryUserByID
+      security:
+        - homeserverAccessToken: []
       parameters:
         - in: query 
           name: userid

api/application-service/query_room.yaml

@@ -20,11 +20,13 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: "/"
+basePath: /_matrix/app/v1
 consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomAlias}":
     get:
@@ -36,6 +38,8 @@ paths:
         homeserver will send this request when it receives a request to join a
         room alias within the application service's namespace.
       operationId: queryRoomByAlias
+      security:
+        - homeserverAccessToken: []
       parameters:
         - in: path
           name: roomAlias

api/application-service/query_user.yaml

@@ -20,11 +20,13 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: "/"
+basePath: /_matrix/app/v1
 consumes:
   - application/json
 produces:
   - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/users/{userId}":
     get:
@@ -36,6 +38,8 @@ paths:
         send this request when it receives an event for an unknown user ID in
         the application service's namespace, such as a room invite.
       operationId: queryUserById
+      security:
+        - homeserverAccessToken: []
       parameters:
         - in: path
           name: userId

api/application-service/transactions.yaml

@@ -0,0 +1,78 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+swagger: '2.0'
+info:
+  title: "Matrix Application Service API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/app/v1
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/transactions/{txnId}":
+    put:
+      summary: Send some events to the application service.
+      description: |-
+        This API is called by the homeserver when it wants to push an event
+        (or batch of events) to the application service.
+
+        Note that the application service should distinguish state events
+        from message events via the presence of a ``state_key``, rather than
+        via the event type.
+      operationId: sendTransaction
+      security:
+        - homeserverAccessToken: []
+      parameters:
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this set of events. Homeservers generate
+            these IDs and they are used to ensure idempotency of requests.
+          required: true
+          x-example: "35"
+        - in: body
+          name: body
+          description: A list of events.
+          schema:
+            type: object
+            example: {
+              "events": [
+                {"$ref": "../../event-schemas/examples/m.room.member"},
+                {"$ref": "../../event-schemas/examples/m.room.message#m.text"}
+              ]
+            }
+            description: Transaction information
+            properties:
+              events:
+                type: array
+                description: |-
+                  A list of events, formatted as per the Client-Server API.
+                items:
+                  type: object
+                  title: Event
+            required: ["events"]
+      responses:
+        200:
+          description: The transaction was processed successfully.
+          examples:
+            application/json: {}
+          schema:
+            type: object

api/client-server/admin.yaml

@@ -105,7 +105,8 @@ paths:
                                   type: string
                                   description: Most recently seen IP address of the session.
                                 last_seen:
-                                  type: number
+                                  type: integer
+                                  format: int64
                                   description: Unix timestamp that the session was last active.
                                 user_agent:
                                   type: string

api/client-server/administrative_contact.yaml

@@ -47,13 +47,15 @@ paths:
           description: The lookup was successful.
           examples:
             application/json: {
-                "threepids": [
+              "threepids": [
-                  {
+                {
-                    "medium": "email",
+                  "medium": "email",
-                    "address": "monkey@banana.island"
+                  "address": "monkey@banana.island",
-                  }
+                  "validated_at": 1535176800000,
-                ]
+                  "added_at": 1535336848756
-              }
+                }
+              ]
+            }
           schema:
             type: object
             properties:
@@ -70,6 +72,19 @@ paths:
                     address:
                       type: string
                       description: The third party identifier address.
+                    validated_at:
+                      type: integer
+                      format: int64
+                      description: |-
+                        The timestamp, in milliseconds, when the identifier was
+                        validated by the identity service.
+                    added_at:
+                      type: integer
+                      format: int64
+                      description:
+                        The timestamp, in milliseconds, when the homeserver
+                        associated the third party identifier with the user.
+                  required: ['medium', 'address', 'validated_at', 'added_at']
       tags:
         - User data
     post:
@@ -133,6 +148,41 @@ paths:
             "$ref": "definitions/errors/error.yaml"
       tags:
         - User data
+  "/account/3pid/delete":
+    post:
+      summary: Deletes a third party identifier from the user's account
+      description: |-
+        Removes a third party identifier from the user's account. This might not
+        cause an unbind of the identifier from the identity service.
+      operationId: delete3pidFromAccount
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              medium:
+                type: string
+                description: The medium of the third party identifier being removed.
+                enum: ["email", "msisdn"]
+                example: "email"
+              address:
+                type: string
+                description: The third party address being removed.
+                example: "example@domain.com"
+            required: ['medium', 'address']
+      responses:
+        200:
+          description: |-
+            The homeserver has disassociated the third party identifier from the
+            user.
+          schema:
+            type: object
+            properties: {}
+      tags:
+        - User data
   "/account/3pid/email/requestToken":
     post:
       summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account

api/client-server/appservice_room_directory.yaml

@@ -0,0 +1,88 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Application Service Room Directory API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  # Note: this is the same access_token definition used elsewhere in the client
+  # server API, however this expects an access token for an application service.
+  $ref: definitions/security.yaml
+paths:
+  "/directory/list/appservice/{networkId}/{roomId}":
+    put:
+      summary: |-
+        Updates a room's visibility in the application service's room directory.
+      description: |-
+        Updates the visibility of a given room on the application service's room
+        directory.
+
+        This API is similar to the room directory visibility API used by clients
+        to update the homeserver's more general room directory.
+
+        This API requires the use of an application service access token (``as_token``)
+        instead of a typical client's access_token. This API cannot be invoked by
+        users who are not identified as application services.
+      operationId: updateAppserviceRoomDirectoryVsibility
+      parameters:
+        - in: path
+          type: string
+          name: networkId
+          description: |-
+            The protocol (network) ID to update the room list for. This would
+            have been provided by the application service as being listed as
+            a supported protocol.
+          required: true
+          x-example: "irc"
+        - in: path
+          type: string
+          name: roomId
+          description: The room ID to add to the directory.
+          required: true
+          x-example: "!somewhere:domain.com"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            properties:
+              visibility:
+                type: string
+                enum: ["public", "private"]
+                description: |-
+                  Whether the room should be visible (public) in the directory
+                  or not (private).
+                example: "public"
+            required: ['visibility']
+      security:
+        # again, this is the appservice's token - not a typical client's
+        - accessToken: []
+      responses:
+        200:
+          description: The room's directory visibility has been updated.
+          schema:
+            type: object
+          examples:
+            application/json: {}
+      tags:
+        - Application service room directory management

api/client-server/content-repo.yaml

@@ -259,7 +259,8 @@ paths:
           description: "The URL to get a preview of"
           required: true
         - in: query
-          type: number
+          type: integer
+          format: int64
           x-example: 1510610716656
           name: ts
           description: |-
@@ -276,7 +277,8 @@ paths:
             type: object
             properties:
               "matrix:image:size":
-                type: number
+                type: integer
+                format: int64
                 description: |-
                   The byte-size of the image. Omitted if there is no image attached.
               "og:image":
@@ -324,7 +326,8 @@ paths:
             type: object
             properties:
               m.upload.size:
-                type: number
+                type: integer
+                format: int64
                 description: |- 
                   The maximum size an upload can be in bytes.
                   Clients SHOULD use this as a guide when uploading content.

api/client-server/definitions/event_filter.yaml

@@ -11,7 +11,7 @@
 # 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.
-title: Filter
+title: EventFilter
 properties:
   limit:
     description: The maximum number of events to return.

api/client-server/definitions/public_rooms_response.yaml

@@ -45,7 +45,7 @@ properties:
           description: |-
             The name of the room, if any.
         num_joined_members:
-          type: number
+          type: integer
           description: |-
             The number of members joined to the room.
         room_id:
@@ -82,7 +82,7 @@ properties:
       absence of this token means there are no results before this
       batch, i.e. this is the first batch.
   total_room_count_estimate:
-    type: number
+    type: integer
     description: |-
         An estimate on the total number of public rooms, if the
         server has an estimate.

api/client-server/definitions/room_event_filter.yaml

@@ -13,23 +13,23 @@
 # limitations under the License.
 allOf:
 - $ref: event_filter.yaml
-title: RoomEventFilter
+- type: object
-properties:
+  title: RoomEventFilter
-  not_rooms:
+  properties:
-    description: A list of room IDs to exclude. If this list is absent then no rooms
+    not_rooms:
-      are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
+      description: A list of room IDs to exclude. If this list is absent then no rooms
-      filter.
+        are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
-    items:
+        filter.
-      type: string
+      items:
-    type: array
+        type: string
-  rooms:
+      type: array
-    description: A list of room IDs to include. If this list is absent then all rooms
+    rooms:
-      are included.
+      description: A list of room IDs to include. If this list is absent then all rooms
-    items:
+        are included.
-      type: string
+      items:
-    type: array
+        type: string
-  contains_url:
+      type: array
-    type: boolean
+    contains_url:
-    description: If ``true``, includes only events with a url key in their content. If
+      type: boolean
-      ``false``, excludes those events.
+      description: If ``true``, includes only events with a ``url`` key in their content. If
-type: object
+        ``false``, excludes those events. Defaults to ``false``.

api/client-server/definitions/sync_filter.yaml

@@ -11,6 +11,8 @@
 # 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: Filter
 properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
@@ -40,6 +42,7 @@ properties:
   room:
     title: RoomFilter
     description: Filters to be applied to room data.
+    type: object
     properties:
       not_rooms:
         description: A list of room IDs to exclude. If this list is absent then no rooms
@@ -76,5 +79,3 @@ properties:
         allOf:
         - $ref: room_event_filter.yaml
         description: The per user account data to include for rooms.
-    type: object
-type: object

api/client-server/definitions/wellknown/homeserver.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+title: Homeserver Information
+description: |-
+  Used by clients to discover homeserver information.
+type: object
+properties:
+  base_url:
+    type: string
+    description: The base URL for the homeserver for client-server connections.
+    example: https://matrix.example.com
+required:
+  - base_url

api/client-server/definitions/wellknown/identity_server.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+title: Identity Server Information
+description: |-
+  Used by clients to discover identity server information.
+type: object
+properties:
+  base_url:
+    type: string
+    description: The base URL for the identity server for client-server connections.
+    example: https://identity.example.com
+required:
+  - base_url

api/client-server/directory.yaml

@@ -41,7 +41,7 @@ paths:
           required: true
           x-example: "#monkeys:matrix.org"
         - in: body
-          name: roomInfo
+          name: body
           description: Information about this room alias.
           required: true
           schema:
@@ -50,24 +50,24 @@ paths:
               room_id:
                 type: string
                 description: The room ID to set.
+            required: ['room_id']
             example: {
-                "room_id": "!abnjk1jdasj98:capuchins.com"
+              "room_id": "!abnjk1jdasj98:capuchins.com"
-              }
+            }
       responses:
         200:
           description: The mapping was created.
           examples:
-            application/json: {
+            application/json: {}
-              }
           schema:
             type: object
         409:
           description: A room alias with that name already exists.
           examples:
             application/json: {
-                "errcode": "M_UNKNOWN",
+              "errcode": "M_UNKNOWN",
-                "error": "Room alias #monkeys:matrix.org already exists."
+              "error": "Room alias #monkeys:matrix.org already exists."
-              }
+            }
           schema:
             "$ref": "definitions/errors/error.yaml"
       tags:

api/client-server/filter.yaml

@@ -54,44 +54,45 @@ paths:
             allOf:
               - $ref: "definitions/sync_filter.yaml"
             example: {
-                "room": {
+              "room": {
-                  "state": {
+                "state": {
-                    "types": ["m.room.*"],
+                  "types": ["m.room.*"],
-                    "not_rooms": ["!726s6s6q:example.com"]
+                  "not_rooms": ["!726s6s6q:example.com"]
-                  },
-                  "timeline": {
-                    "limit": 10,
-                    "types": ["m.room.message"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  },
-                  "ephemeral": {
-                    "types": ["m.receipt", "m.typing"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  }
                 },
-                "presence": {
+                "timeline": {
-                  "types": ["m.presence"],
+                  "limit": 10,
-                  "not_senders": ["@alice:example.com"]
+                  "types": ["m.room.message"],
+                  "not_rooms": ["!726s6s6q:example.com"],
+                  "not_senders": ["@spam:example.com"]
                 },
-                "event_format": "client",
+                "ephemeral": {
-                "event_fields": ["type", "content", "sender"]
+                  "types": ["m.receipt", "m.typing"],
-              }
+                  "not_rooms": ["!726s6s6q:example.com"],
+                  "not_senders": ["@spam:example.com"]
+                }
+              },
+              "presence": {
+                "types": ["m.presence"],
+                "not_senders": ["@alice:example.com"]
+              },
+              "event_format": "client",
+              "event_fields": ["type", "content", "sender"]
+            }
       responses:
         200:
           description: The filter was created.
-          examples:
-            application/json: {
-                "filter_id": "66696p746572"
-              }
           schema:
             type: object
             properties:
               filter_id:
                 type: string
                 description: |-
-                  The ID of the filter that was created.
+                  The ID of the filter that was created. Cannot start
+                  with a ``{`` as this character is used to determine
+                  if the filter provided is inline JSON or a previously
+                  declared filter by homeservers on some APIs.
+                example: "66696p746572"
+            required: ['filter_id']
       tags:
         - Room participation
   "/user/{userId}/filter/{filterId}":

api/client-server/list_public_rooms.yaml

@@ -123,7 +123,7 @@ paths:
       parameters:
         - in: query
           name: limit
-          type: number
+          type: integer
           description: |-
             Limit the number of results returned.
         - in: query
@@ -173,7 +173,7 @@ paths:
             type: object
             properties:
               limit:
-                type: number
+                type: integer
                 description: |-
                   Limit the number of results returned.
               since:
@@ -194,8 +194,26 @@ paths:
                       description: |-
                         A string to search for in the room metadata, e.g. name,
                         topic, canonical alias etc. (Optional).
+              include_all_networks:
+                type: boolean
+                description: |-
+                  Whether or not to include all known networks/protocols from
+                  application services on the homeserver. Defaults to false.
+                example: false
+              third_party_instance_id:
+                type: string
+                description: |-
+                  The specific third party network/protocol to request from the
+                  homeserver. Can only be used if ``include_all_networks`` is false.
+                example: "irc"
             example: {
-              "limit": 10, "filter": {"generic_search_term": "foo"}}
+              "limit": 10, 
+              "filter": {
+                "generic_search_term": "foo"
+              },
+              "include_all_networks": false,
+              "third_party_instance_id": "irc"
+            }
       responses:
         200:
           description: A list of the rooms on the server.
@@ -233,7 +251,7 @@ paths:
                       description: |-
                         The name of the room, if any.
                     num_joined_members:
-                      type: number
+                      type: integer
                       description: |-
                         The number of members joined to the room.
                     room_id:
@@ -270,7 +288,7 @@ paths:
                   absence of this token means there are no results before this
                   batch, i.e. this is the first batch.
               total_room_count_estimate:
-                type: number
+                type: integer
                 description: |-
                    An estimate on the total number of public rooms, if the
                    server has an estimate.

api/client-server/notifications.yaml

@@ -45,7 +45,7 @@ paths:
           required: false
           x-example: "xxxxx"
         - in: query
-          type: number
+          type: integer
           name: limit
           description: Limit on the number of events to return in this request.
           required: false

api/client-server/pushrules.yaml

@@ -343,6 +343,8 @@ paths:
         This endpoint allows the creation, modification and deletion of pushers
         for this user ID. The behaviour of this endpoint varies depending on the
         values in the JSON body.
+
+        When creating push rules, they MUST be enabled by default.
       operationId: setPushRule
       security:
         - accessToken: []
@@ -424,7 +426,7 @@ paths:
             required: ["actions"]
       responses:
         200:
-          description: The pusher was set.
+          description: The push rule was created/updated.
           examples:
             application/json: {
               }

api/client-server/registration.yaml

@@ -117,6 +117,13 @@ paths:
                   A display name to assign to the newly-created device. Ignored
                   if ``device_id`` corresponds to a known device.
                 example: Jungle Phone
+              inhibit_login:
+                type: boolean
+                description: |-
+                  If true, an ``access_token`` and ``device_id`` should not be
+                  returned from this call, therefore preventing an automatic
+                  login. Defaults to false.
+                example: false
       responses:
         200:
           description: The account has been registered.
@@ -141,6 +148,7 @@ paths:
                 description: |-
                   An access token for the account.
                   This access token can then be used to authorize other requests.
+                  Required if the ``inhibit_login`` option is false.
               home_server:
                 type: string
                 description: |-
@@ -155,6 +163,8 @@ paths:
                 description: |-
                   ID of the registered device. Will be the same as the
                   corresponding parameter in the request, if one was specified.
+                  Required if the ``inhibit_login`` option is false.
+            required: ['user_id']
         400:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
@@ -218,7 +228,7 @@ paths:
                 description: The email address
                 example: "example@example.com"
               send_attempt:
-                type: number
+                type: integer
                 description: Used to distinguish protocol level retries from requests to re-send the email.
                 example: 1
             required: ["client_secret", "email", "send_attempt"]
@@ -283,7 +293,7 @@ paths:
                 description: The phone number.
                 example: "example@example.com"
               send_attempt:
-                type: number
+                type: integer
                 description: Used to distinguish protocol level retries from requests to re-send the SMS message.
                 example: 1
             required: ["client_secret", "country", "phone_number", "send_attempt"]

api/client-server/room_state.yaml

@@ -87,6 +87,16 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+        403:
+          description: |-
+            The sender doesn't have permission to send the event into the room.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You do not have permission to send the event."
+            }
       tags:
         - Room participation
   "/rooms/{roomId}/state/{eventType}":
@@ -142,5 +152,15 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+        403:
+          description: |-
+            The sender doesn't have permission to send the event into the room.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You do not have permission to send the event."
+            }
       tags:
         - Room participation

api/client-server/search.yaml

@@ -41,7 +41,7 @@ paths:
           type: string
           description: |-
             The point to return events from. If given, this should be a
-            `next_batch` result from a previous call to this endpoint.
+            ``next_batch`` result from a previous call to this endpoint.
           x-example: "YWxsCgpOb25lLDM1ODcwOA"
         - in: body
           name: body
@@ -95,6 +95,7 @@ paths:
                         # for now :/
                         description: |-
                           This takes a `filter`_.
+                        $ref: "definitions/room_event_filter.yaml"
                       order_by:
                         title: "Ordering"
                         type: string
@@ -179,7 +180,7 @@ paths:
                     description: Mapping of category name to search criteria.
                     properties:
                       count:
-                        type: number
+                        type: integer
                         description: An approximate count of the total number of results found.
                       highlights:
                         type: array

api/client-server/sync.yaml

@@ -77,13 +77,14 @@ paths:
         - in: query
           name: set_presence
           type: string
-          enum: ["offline"]
+          enum: ["offline", "online", "unavailable"]
           description: |-
             Controls whether the client is automatically marked as online by
             polling this API. If this parameter is omitted then the client is
             automatically marked as online when it uses this API. Otherwise if
             the parameter is set to "offline" then the client is not marked as
-            being online when it uses this API.
+            being online when it uses this API. When set to "unavailable", the
+            client is marked as being idle.
           x-example: "offline"
         - in: query
           name: timeout
@@ -227,6 +228,14 @@ paths:
                             room up to the point when the user left.
                           allOf:
                             - $ref: "definitions/timeline_batch.yaml"
+                        account_data:
+                          title: Account Data
+                          type: object
+                          description: |-
+                            The private data that this user has attached to
+                            this room.
+                          allOf:
+                          - $ref: "definitions/event_batch.yaml"
               presence:
                 title: Presence
                 type: object

api/client-server/tags.yaml

@@ -43,14 +43,14 @@ paths:
           required: true
           description: |-
             The id of the user to get tags for. The access token must be
-            authorized to make requests for this user id.
+            authorized to make requests for this user ID.
           x-example: "@alice:example.com"
         - in: path
           type: string
           name: roomId
           required: true
           description: |-
-            The id of the room to get tags for.
+            The ID of the room to get tags for.
           x-example: "!726s6s6q:example.com"
       responses:
         200:
@@ -60,16 +60,26 @@ paths:
             type: object
             properties:
               tags:
-                title: Tags
                 type: object
+                additionalProperties:
+                  title: Tag
+                  type: object
+                  properties:
+                    order:
+                      type: number
+                      format: float
+                      description: |-
+                        A number in a range ``[0,1]`` describing a relative
+                        position of the room under the given tag.
+                  additionalProperties: true
           examples:
             application/json: {
-                "tags": {
+              "tags": {
-                  "m.favourite": {},
+                "m.favourite": {"order": 0.1},
-                  "u.Work": {"order": "1"},
+                "u.Work": {"order": 0.7},
-                  "u.Customers": {}
+                "u.Customers": {}
-                }
               }
+            }
       tags:
         - User data
   "/user/{userId}/rooms/{roomId}/tags/{tag}":
@@ -87,14 +97,14 @@ paths:
           required: true
           description: |-
             The id of the user to add a tag for. The access token must be
-            authorized to make requests for this user id.
+            authorized to make requests for this user ID.
           x-example: "@alice:example.com"
         - in: path
           type: string
           name: roomId
           required: true
           description: |-
-            The id of the room to add a tag to.
+            The ID of the room to add a tag to.
           x-example: "!726s6s6q:example.com"
         - in: path
           type: string
@@ -102,7 +112,7 @@ paths:
           required: true
           description: |-
             The tag to add.
-          x-example: "work"
+          x-example: "u.work"
         - in: body
           name: body
           required: true
@@ -110,8 +120,17 @@ paths:
             Extra data for the tag, e.g. ordering.
           schema:
             type: object
+            properties:
+              order:
+                type: number
+                format: float
+                description: |-
+                  A number in a range ``[0,1]`` describing a relative
+                  position of the room under the given tag.
+            additionalProperties: true
             example: {
-              "order": "1"}
+              "order": 0.25
+            }
       responses:
         200:
           description:
@@ -119,8 +138,7 @@ paths:
           schema:
             type: object
           examples:
-            application/json: {
+            application/json: {}
-              }
       tags:
         - User data
     delete:
@@ -137,14 +155,14 @@ paths:
           required: true
           description: |-
             The id of the user to remove a tag for. The access token must be
-            authorized to make requests for this user id.
+            authorized to make requests for this user ID.
           x-example: "@alice:example.com"
         - in: path
           type: string
           name: roomId
           required: true
           description: |-
-            The id of the room to remove a tag from.
+            The ID of the room to remove a tag from.
           x-example: "!726s6s6q:example.com"
         - in: path
           type: string
@@ -152,15 +170,14 @@ paths:
           required: true
           description: |-
             The tag to remove.
-          x-example: "work"
+          x-example: "u.work"
       responses:
         200:
           description:
-            The tag was successfully removed
+            The tag was successfully removed.
           schema:
             type: object
           examples:
-            application/json: {
+            application/json: {}
-              }
       tags:
         - User data

api/client-server/third_party_lookup.yaml

@@ -73,7 +73,7 @@ paths:
             $ref: definitions/errors/error.yaml
   "/thirdparty/location/{protocol}":
     get:
-      summary: Retreive Matrix-side portals rooms leading to a third party location.
+      summary: Retrieve Matrix-side portals rooms leading to a third party location.
       description: |-
         Requesting this endpoint with a valid protocol name results in a list
         of successful mapping results in a JSON array. Each result contains
@@ -151,7 +151,7 @@ paths:
     get:
       summary: Reverse-lookup third party locations given a Matrix room alias.
       description: |-
-        Retreive an array of third party network locations from a Matrix room
+        Retrieve an array of third party network locations from a Matrix room
         alias.
       operationId: queryLocationByAlias
       security:
@@ -181,7 +181,7 @@ paths:
     get:
       summary: Reverse-lookup third party users given a Matrix User ID.
       description: |-
-        Retreive an array of third party users from a Matrix User ID.
+        Retrieve an array of third party users from a Matrix User ID.
       operationId: queryUserByID
       security:
         - accessToken: []

api/client-server/users.yaml

@@ -31,8 +31,16 @@ paths:
     post:
       summary: Searches the user directory.
       description: |-
-        This API performs a server-side search over all users registered on the server.
+        Performs a search for users on the homeserver. The homeserver may
-        It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.
+        determine which subset of users are searched, however the homeserver
+        MUST at a minimum consider the users the requesting user shares a
+        room with and those who reside in public rooms (known to the homeserver).
+        The search MUST consider local users to the homeserver, and SHOULD
+        query remote users as part of the search.
+
+        The search is performed case-insensitively on user IDs and display
+        names preferably using a collation determined based upon the 
+        ``Accept-Language`` header provided in the request, if present.
       operationId: searchUserDirectory
       security:
         - accessToken: []
@@ -47,8 +55,8 @@ paths:
                 description: The term to search for
                 example: "foo"
               limit:
-                type: number
+                type: integer
-                description: The maximum number of results to return (Defaults to 10).
+                description: The maximum number of results to return. Defaults to 10.
                 example: 10
             required: ["search_term"]
       responses:
@@ -56,15 +64,15 @@ paths:
           description: The results of the search.
           examples:
             application/json: {
-                  "results": [
+              "results": [
-                    {
+                {
-                      "user_id": "@foo:bar.com",
+                  "user_id": "@foo:bar.com",
-                      "display_name": "Foo",
+                  "display_name": "Foo",
-                      "avatar_url": "mxc://bar.com/foo"
+                  "avatar_url": "mxc://bar.com/foo"
-                    }
+                }
-                  ],
+              ],
-                  "limited": false
+              "limited": false
-              }
+            }
           schema:
             type: object
             required: ["results", "limited"]

api/client-server/wellknown.yaml

@@ -0,0 +1,66 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Server Discovery API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+basePath: /.well-known
+produces:
+  - application/json
+paths:
+  "/matrix/client":
+    get:
+      summary: Gets Matrix server discovery information about the domain.
+      description: |-
+        Gets discovery information about the domain. The file may include
+        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.
+
+        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:
+          description: Server discovery information.
+          examples:
+            application/json: {
+                "m.homeserver": {
+                  "base_url": "https://matrix.example.com"
+                },
+                "m.identity_server": {
+                  "base_url": "https://identity.example.com"
+                }
+              }
+          schema:
+            type: object
+            properties:
+              m.homeserver:
+                description: Information about the homeserver to connect to.
+                "$ref": "definitions/wellknown/homeserver.yaml"
+              m.identity_server:
+                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:
+        - Server administration

api/identity/associations.yaml

@@ -18,15 +18,17 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
   "/3pid/getValidated3pid":
     get:
       summary: Check whether ownership of a 3pid was validated.
-      description: A client can check whether ownership of a 3pid was validated
+      description: |-
+        Determines if a given 3pid has been validated by a user.
       operationId: getValidated3pid
       parameters:
         - in: query
@@ -46,10 +48,10 @@ paths:
           description: Validation information for the session.
           examples:
             application/json: {
-                "medium": "email",
+              "medium": "email",
-                "validated_at": 1457622739026,
+              "validated_at": 1457622739026,
-                "address": "louise@bobs.burgers"
+              "address": "louise@bobs.burgers"
-              }
+            }
           schema:
             type: object
             properties:
@@ -61,7 +63,10 @@ paths:
                 description: The address of the 3pid being looked up.
               validated_at:
                 type: integer
-                description: Timestamp indicating the time that the 3pid was validated.
+                description: |-
+                  Timestamp, in milliseconds, indicating the time that the 3pid
+                  was validated.
+            required: ['medium', 'address', 'validated_at']
         400:
           description: |-
             The session has not been validated.
@@ -71,16 +76,20 @@ paths:
             ``errcode`` will be ``M_SESSION_EXPIRED``.
           examples:
             application/json: {
-                "errcode": "M_SESSION_NOT_VALIDATED",
+              "errcode": "M_SESSION_NOT_VALIDATED",
-                "error": "This validation session has not yet been completed"
+              "error": "This validation session has not yet been completed"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
-          description: The Session ID or client secret were not found
+          description: The Session ID or client secret were not found.
           examples:
             application/json: {
-                "errcode": "M_NO_VALID_SESSION",
+              "errcode": "M_NO_VALID_SESSION",
-                "error": "No valid session was found matching that sid and client secret"
+              "error": "No valid session was found matching that sid and client secret"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/bind":
     post:
       summary: Publish an association between a session and a Matrix user ID.
@@ -90,7 +99,7 @@ paths:
         Future calls to ``/lookup`` for any of the session\'s 3pids will return
         this association.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is
         deprecated.
@@ -101,10 +110,10 @@ paths:
           schema:
             type: object
             example: {
-                "sid": "1234",
+              "sid": "1234",
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "mxid": "@ears:matrix.org"
+              "mxid": "@ears:matrix.org"
-              }
+            }
             properties:
               sid:
                 type: string
@@ -121,19 +130,18 @@ paths:
           description: The association was published.
           examples:
             application/json: {
-                "address": "louise@bobs.burgers",
+              "address": "louise@bobs.burgers",
-                "medium": "email",
+              "medium": "email",
-                "mxid": "@ears:matrix.org",
+              "mxid": "@ears:matrix.org",
-                "not_before": 1428825849161,
+              "not_before": 1428825849161,
-                "not_after": 4582425849161,
+              "not_after": 4582425849161,
-                "ts": 1428825849161,
+              "ts": 1428825849161,
-
+              "signatures": {
-                "signatures": {
+                "matrix.org": {
-                  "matrix.org": {
+                  "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                    "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                  }
                 }
               }
+            }
           schema:
             type: object
             properties:
@@ -157,7 +165,19 @@ paths:
                 description: The unix timestamp at which the association was verified.
               signatures:
                 type: object
-                description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                description: |-
+                  The signatures of the verifying identity services which show that the
+                  association should be trusted, if you trust the verifying identity
+                  services.
+                $ref: "../../schemas/server-signatures.yaml"
+            required:
+              - address
+              - medium
+              - mxid
+              - not_before
+              - not_after
+              - ts
+              - signatures
         400:
           description: |-
             The association was not published.
@@ -167,13 +187,17 @@ paths:
             ``errcode`` will be ``M_SESSION_EXPIRED``.
           examples:
             application/json: {
-                "errcode": "M_SESSION_NOT_VALIDATED",
+              "errcode": "M_SESSION_NOT_VALIDATED",
-                "error": "This validation session has not yet been completed"
+              "error": "This validation session has not yet been completed"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
           description: The Session ID or client secret were not found
           examples:
             application/json: {
-                "errcode": "M_NO_VALID_SESSION",
+              "errcode": "M_NO_VALID_SESSION",
-                "error": "No valid session was found matching that sid and client secret"
+              "error": "No valid session was found matching that sid and client secret"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/email_associations.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -34,13 +35,13 @@ paths:
         that that user was able to read the email for that email address, and
         so we validate ownership of the email address.
 
-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
         additional behaviour on top, for example,
         ``/register/email/requestToken`` is designed specifically for use when
         registering an account and therefore will inform the user if the email
         address given is already registered on the server.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is
         deprecated.
@@ -51,14 +52,14 @@ paths:
           schema:
             type: object
             example: {
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "email": "foo@example.com",
+              "email": "foo@example.com",
-                "send_attempt": 1
+              "send_attempt": 1
-              }
+            }
             properties:
               client_secret:
                 type: string
-                description: A unique string used to identify the validation attempt
+                description: A unique string used to identify the validation attempt.
               email:
                 type: string
                 description: The email address to validate.
@@ -85,20 +86,28 @@ paths:
             Session created.
           examples:
             application/json: {
-                "sid": "1234"
+              "sid": "1234"
-              }
+            }
           schema:
             type: object
             properties:
               sid:
                 type: string
                 description: The session ID.
+            required: ['sid']
         400:
           description: |
             An error ocurred.  Some possible errors are:
 
             - ``M_INVALID_EMAIL``: The email address provided was invalid.
             - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_EMAIL",
+              "error": "The email address is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/email/submitToken":
     post:
       summary: Validate ownership of an email address.
@@ -111,7 +120,7 @@ paths:
         associate the email address with any Matrix user ID. Specifically,
         calls to ``/lookup`` will not show a binding.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is
         deprecated.
@@ -122,10 +131,10 @@ paths:
           schema:
             type: object
             example: {
-                "sid": "1234",
+              "sid": "1234",
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "token": "atoken"
+              "token": "atoken"
-              }
+            }
             properties:
               sid:
                 type: string
@@ -143,14 +152,15 @@ paths:
             The success of the validation.
           examples:
             application/json: {
-                "success": true
+              "success": true
-              }
+            }
           schema:
             type: object
             properties:
               success:
                 type: boolean
                 description: Whether the validation was successful or not.
+            required: ['success']
     get:
       summary: Validate ownership of an email address.
       description: |-

api/identity/invitation_signing.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -29,7 +30,7 @@ paths:
       description: |-
         Sign invitation details.
 
-        The identity server will look up ``token`` which was stored in a call
+        The identity service will look up ``token`` which was stored in a call
         to ``store-invite``, and fetch the sender of the invite.
       operationId: blindlySignStuff
       parameters:
@@ -38,24 +39,24 @@ paths:
           schema:
             type: object
             example: {
-                "mxid": "@foo:bar.com",
+              "mxid": "@foo:bar.com",
-                "token": "sometoken",
+              "token": "sometoken",
-                "private_key": "base64encodedkey"
+              "private_key": "base64encodedkey"
-              }
+            }
             properties:
               mxid:
                 type: string
                 description: The Matrix user ID of the user accepting the invitation.
               token:
                 type: string
-                description: Token from the call to ``store-invite``
+                description: The token from the call to ``store-invite``.
               private_key:
                 type: string
                 description: The private key, encoded as `Unpadded base64`_.
             required: ["mxid", "token", "private_key"]
       responses:
         200:
-          description: The signedjson of the mxid, sender, and token.
+          description: The signed JSON of the mxid, sender, and token.
           schema:
             type: object
             properties:
@@ -68,9 +69,11 @@ paths:
               signatures:
                 type: object
                 description: The signature of the mxid, sender, and token.
+                $ref: "../../schemas/server-signatures.yaml"
               token:
                 type: string
                 description: The token for the invitation.
+            required: ['mxid', 'sender', 'signatures', 'token']
           examples:
             application/json: {
               "mxid": "@foo:bar.com",
@@ -83,8 +86,11 @@ paths:
               "token": "abc123"
             }
         404:
-          description: Token was not found.
+          description: The token was not found.
-          example: {
+          examples: 
+            application/json: {
               "errcode": "M_UNRECOGNIZED",
               "error": "Didn't recognize token"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/lookup.yaml

@@ -1,6 +1,7 @@
 # Copyright 2016 OpenMarket Ltd
 # Copyright 2017 Kamax.io
 # Copyright 2017 New Vector Ltd
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -20,8 +21,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -46,31 +48,30 @@ paths:
       responses:
         200:
           description:
-            The association for that 3pid, or the empty object if no association is known.
+            The association for that 3pid, or an empty object if no association is known.
           examples:
             application/json: {
-                "address": "louise@bobs.burgers",
+              "address": "louise@bobs.burgers",
-                "medium": "email",
+              "medium": "email",
-                "mxid": "@ears:matrix.org",
+              "mxid": "@ears:matrix.org",
-                "not_before": 1428825849161,
+              "not_before": 1428825849161,
-                "not_after": 4582425849161,
+              "not_after": 4582425849161,
-                "ts": 1428825849161,
+              "ts": 1428825849161,
-
+              "signatures": {
-                "signatures": {
+                "matrix.org": {
-                  "matrix.org": {
+                  "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                    "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                  }
                 }
               }
+            }
           schema:
             type: object
             properties:
               address:
                 type: string
-                description: The 3pid address of the user being looked up.
+                description: The 3pid address of the user being looked up, matching the address requested.
               medium:
                 type: string
-                description: The literal string "email".
+                description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
               mxid:
                 type: string
                 description: The Matrix user ID associated with the 3pid.
@@ -86,6 +87,15 @@ paths:
               signatures:
                 type: object
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                $ref: "../../schemas/server-signatures.yaml"
+            required:
+              - address
+              - medium
+              - mxid
+              - not_before
+              - not_after
+              - ts
+              - signatures
   "/bulk_lookup":
     post:
       summary: Lookup Matrix user IDs for a list of 3pids.
@@ -110,10 +120,17 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 2
+                  maxItems: 2
                   items:
-                    type: string
+                    # TODO: Give real names to these values. Adding a `title` does not work.
-                    title: 3PID medium or address
+                    #- type: 3PID Medium
-                description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
+                    #- type: 3PID Address
+                    - type: string
+                    - type: string
+                description: |-
+                  An array of arrays containing the `3PID Types`_ with the ``medium``
+                  in first position and the ``address`` in second position.
             required:
               - "threepids"
       responses:
@@ -134,9 +151,19 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 3
+                  maxItems: 3
                   items:
-                    type: string
+                    # TODO: Give real names to these values. Adding a `title` does not work.
-                    title: 3PID medium or address or the Matrix ID
+                    #- type: 3PID Medium
-                description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
+                    #- type: 3PID Address
+                    #- type: Matrix User ID
+                    - type: string
+                    - type: string
+                    - type: string
+                description: |-
+                  An array of array containing the `3PID Types`_ with the ``medium``
+                  in first position, the ``address`` in second position and Matrix user
+                  ID in third position.
             required:
               - "threepids"

api/identity/phone_associations.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -34,13 +35,13 @@ paths:
         indicates that that user was able to read the SMS for that phone
         number, and so we validate ownership of the phone number.
 
-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
         additional behaviour on top, for example,
         ``/register/msisdn/requestToken`` is designed specifically for use when
         registering an account and therefore will inform the user if the phone
         number given is already registered on the server.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data. However, this usage is
         deprecated.
@@ -51,11 +52,11 @@ paths:
           schema:
             type: object
             example: {
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "country": "GB",
+              "country": "GB",
-                "phone_number": "07700900001",
+              "phone_number": "07700900001",
-                "send_attempt": 1
+              "send_attempt": 1
-              }
+            }
             properties:
               client_secret:
                 type: string
@@ -91,20 +92,30 @@ paths:
             Session created.
           examples:
             application/json: {
-                "sid": "1234"
+              "sid": "1234"
-              }
+            }
           schema:
             type: object
             properties:
               sid:
                 type: string
                 description: The session ID.
+            required: ['sid']
         400:
           description: |
             An error ocurred. Some possible errors are:
 
             - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
             - ``M_SEND_ERROR``: The validation SMS could not be sent.
+            - ``M_DESTINATION_REJECTED``: The identity service cannot deliver an
+              SMS to the provided country or region.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_ADDRESS",
+              "error": "The phone number is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/msisdn/submitToken":
     post:
       summary: Validate ownership of a phone number.
@@ -117,7 +128,7 @@ paths:
         associate the phone number address with any Matrix user
         ID. Specifically, calls to ``/lookup`` will not show a binding.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data. However, this usage is
         deprecated.
@@ -128,10 +139,10 @@ paths:
           schema:
             type: object
             example: {
-                "sid": "1234",
+              "sid": "1234",
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "token": "atoken"
+              "token": "atoken"
-              }
+            }
             properties:
               sid:
                 type: string
@@ -149,14 +160,15 @@ paths:
             The success of the validation.
           examples:
             application/json: {
-                "success": true
+              "success": true
-              }
+            }
           schema:
             type: object
             properties:
               success:
                 type: boolean
                 description: Whether the validation was successful or not.
+            required: ['success']
     get:
       summary: Validate ownership of a phone number.
       description: |-

api/identity/ping.yaml

@@ -1,4 +1,5 @@
 # Copyright 2018 Kamax Sàrl
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +15,7 @@
 
 swagger: "2.0"
 info:
-  title: "Matrix Client-Identity Versions API"
+  title: "Matrix Identity Service Ping API"
   version: "1.0.0"
 host: localhost:8090
 schemes:
@@ -25,19 +26,19 @@ produces:
 paths:
   "/api/v1":
     get:
-      summary: Checks that an Identity server is available at this API endpopint.
+      summary: Checks that an Identity Service is available at this API endpoint.
       description: |-
-        Checks that an Identity server is available at this API endpopint.
+        Checks that an Identity Service is available at this API endpoint.
 
-        To discover that an Identity server is available at a specific URL,
+        To discover that an Identity Service is available at a specific URL,
         this endpoint can be queried and will return an empty object.
 
         This is primarly used for auto-discovery and health check purposes
-        by entities acting as a client for the Identity server.
+        by entities acting as a client for the Identity Service.
       operationId: ping
       responses:
         200:
-          description: An Identity server is ready to serve requests.
+          description: An Identity Service is ready to serve requests.
           examples:
             application/json: {}
           schema:

api/identity/pubkey.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -45,18 +46,31 @@ paths:
             The public key exists.
           examples:
             application/json: {
-                "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+              "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
-              }
+            }
           schema:
             type: object
             properties:
               public_key:
                 type: string
+                description: Unpadded Base64 encoded public key.
+            required: ['public_key']
+        404:
+          description:
+            The public key was not found.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "The public key was not found"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/pubkey/isvalid":
     get:
       summary: Check whether a long-term public key is valid.
       description: |-
-        Check whether a long-term public key is valid.
+        Check whether a long-term public key is valid. The response should always
+        be the same, provided the key exists.
       operationId: isPubKeyValid
       parameters:
         - in: query
@@ -72,14 +86,15 @@ paths:
             The validity of the public key.
           examples:
             application/json: {
-                "valid": true
+              "valid": true
-              }
+            }
           schema:
             type: object
             properties:
               valid:
                 type: boolean
                 description: Whether the public key is recognised and is currently valid.
+            required: ['valid']
   "/pubkey/ephemeral/isvalid":
     get:
       summary: Check whether a short-term public key is valid.
@@ -100,11 +115,12 @@ paths:
             The validity of the public key.
           examples:
             application/json: {
-                "valid": true
+              "valid": true
-              }
+            }
           schema:
             type: object
             properties:
               valid:
                 type: boolean
                 description: Whether the public key is recognised and is currently valid.
+            required: ['valid']

api/identity/store_invite.yaml

@@ -18,16 +18,17 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
   "/store-invite":
     post:
-      summary: Store pending invitations to a user\'s 3pid.
+      summary: Store pending invitations to a user's 3pid.
       description: |-
-        Store pending invitations to a user\'s 3pid.
+        Store pending invitations to a user's 3pid.
 
         In addition to the request parameters specified below, an arbitrary
         number of other parameters may also be specified. These may be used in
@@ -47,6 +48,8 @@ paths:
 
         Also, the generated ephemeral public key will be listed as valid on
         requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
+
+        Currently, invites may only be issued for 3pids of the ``email`` medium.
       operationId: storeInvite
       parameters:
         - in: body
@@ -54,11 +57,11 @@ paths:
           schema:
             type: object
             example: {
-                "medium": "email",
+              "medium": "email",
-                "address": "foo@bar.baz",
+              "address": "foo@bar.baz",
-                "room_id": "!something:example.tld",
+              "room_id": "!something:example.tld",
-                "sender": "@bob:example.com"
+              "sender": "@bob:example.com"
-              }
+            }
             properties:
               medium:
                 type: string
@@ -84,21 +87,22 @@ paths:
                 description: The generated token.
               public_keys:
                 type: array
-                description: A list of [server\'s long-term public key, generated ephemeral public key].
+                description: A list of [server's long-term public key, generated ephemeral public key].
                 items:
                   type: string
               display_name:
                 type: string
                 description: The generated (redacted) display_name.
+            required: ['token', 'public_keys', 'display_name']
             example:
               application/json: {
-                  "token": "sometoken",
+                "token": "sometoken",
-                  "public_keys": [
+                "public_keys": [
-                    "serverpublickey",
+                  "serverpublickey",
-                    "ephemeralpublickey"
+                  "ephemeralpublickey"
-                  ],
+                ],
-                  "display_name": "f...@b..."
+                "display_name": "f...@b..."
-                }
+              }
         400:
           description: |
             An error has occured.
@@ -108,7 +112,9 @@ paths:
             error code will be ``M_UNRECOGNIZED``.
           examples:
             application/json: {
-                "errcode": "M_THREEPID_IN_USE",
+              "errcode": "M_THREEPID_IN_USE",
-                "error": "Binding already known",
+              "error": "Binding already known",
-                "mxid": mxid
+              "mxid": "@alice:example.com"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/server-server/definitions/pdu.yaml

@@ -23,7 +23,8 @@ allOf:
       hashes:
         type: object
         title: Event Hash
-        description: Hashes of the PDU, following the algorithm specified in `Signing Events`_.
+        description: |-
+          Content hashes of the PDU, following the algorithm specified in `Signing Events`_.
         example: {
           "sha256": "thishashcoversallfieldsincasethisisredacted"
         }

api/server-server/definitions/transaction.yaml

@@ -31,7 +31,7 @@ properties:
     example: 1532991320875
   pdus:
     type: array
-    description: List of persistent updates to rooms.
+    description: List of persistent updates to rooms. Must not include more than 50 PDUs.
     items:
       $ref: "pdu.yaml"
 required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/definitions/unsigned_pdu.yaml

@@ -55,8 +55,8 @@ properties:
   prev_events:
     type: array
     description: |-
-      Event IDs and hashes of the most recent events in the room that the homeserver was aware
+      Event IDs and reference hashes for the most recent events in the room
-      of when it made this event.
+      that the homeserver was aware of when it made this event.
     items:
       type: array
       maxItems: 2
@@ -86,7 +86,7 @@ properties:
   auth_events:
     type: array
     description: |-
-      An event reference list containing the authorization events that would
+      Event IDs and reference hashes for the authorization events that would
       allow this event to be in the room.
     items:
       type: array

api/server-server/events.yaml

@@ -49,7 +49,8 @@ paths:
       responses:
         200:
           description: |-
-            The fully resolved state for the room, including the authorization
+            The fully resolved state for the room, prior to considering any state
+            changes induced by the requested event. Includes the authorization
             chain for the events.
           schema:
             type: object
@@ -96,7 +97,8 @@ paths:
       responses:
         200:
           description: |-
-            The fully resolved state for the room, including the authorization
+            The fully resolved state for the room, prior to considering any state
+            changes induced by the requested event. Includes the authorization
             chain for the events.
           schema:
             type: object

api/server-server/public_rooms.yaml

@@ -49,6 +49,20 @@ paths:
             A pagination token from a previous call to this endpoint to fetch more
             rooms.
           x-example: "GetMoreRoomsTokenHere"
+        - in: query
+          name: include_all_networks
+          type: boolean
+          description: |-
+            Whether or not to include all networks/protocols defined by application
+            services on the homeserver. Defaults to false.
+          x-example: false
+        - in: query
+          name: third_party_instance_id
+          type: string
+          description: |-
+            The specific third party network/protocol to request from the homeserver.
+            Can only be used if ``include_all_networks`` is false.
+          x-example: "irc"
       responses:
         200:
           description: The public room list for the homeserver.

api/server-server/third_party_invite.yaml

@@ -194,3 +194,126 @@ paths:
             type: object
             description: An empty object
             example: {}
+  "/3pid/onbind":
+    put:
+      summary: |-
+        Notifies the server that a third party identifier has been bound to one
+        of its users.
+      description: |-
+        Used by Identity Servers to notify the homeserver that one of its users
+        has bound a third party identifier successfully, including any pending
+        room invites the Identity Server has been made aware of.
+      operationId: onBindThirdPartyIdentifier
+      parameters:
+        - in: body
+          name: body
+          type: object
+          required: true
+          schema:
+            type: object
+            properties:
+              medium:
+                type: string
+                description: |-
+                  The type of third party identifier. Currently only "email" is
+                  a possible value.
+                example: "email"
+              address:
+                type: string
+                description: |-
+                  The third party identifier itself. For example, an email address.
+                example: "alice@domain.com"
+              mxid:
+                type: string
+                description: The user that is now bound to the third party identifier.
+                example: "@alice:matrix.org"
+              invites:
+                type: array
+                description: |-
+                  A list of pending invites that the third party identifier has received.
+                items:
+                  type: object
+                  title: Third Party Invite
+                  properties:
+                    medium:
+                      type: string
+                      description: |-
+                        The type of third party invite issues. Currently only
+                        "email" is used.
+                      example: "email"
+                    address:
+                      type: string
+                      description: |-
+                        The third party identifier that received the invite.
+                      example: "alice@domain.com"
+                    mxid:
+                      type: string
+                      description: The now-bound user ID that received the invite.
+                      example: "@alice:matrix.org"
+                    room_id:
+                      type: string
+                      description: The room ID the invite is valid for.
+                      example: "!somewhere:example.org"
+                    sender:
+                      type: string
+                      description: The user ID that sent the invite.
+                      example: "@bob:matrix.org"
+                    # TODO (TravisR): Make this reusable when doing IS spec changes
+                    #   also make sure it isn't lying about anything, like the key version
+                    signed:
+                      type: object
+                      title: Identity Server Signatures
+                      description: |-
+                        Signature from the Identity Server using a long-term private
+                        key.
+                      properties:
+                        mxid:
+                          type: string
+                          description: |-
+                            The user ID that has been bound to the third party
+                            identifier.
+                          example: "@alice:matrix.org"
+                        token:
+                          type: string
+                          # TODO: What is this actually?
+                          description: A token.
+                          example: "Hello World"
+                        signatures:
+                          type: object
+                          title: Identity Server Signature
+                          description: |-
+                            The signature from the identity server. The ``string`` key
+                            is the identity server's domain name, such as vector.im
+                          additionalProperties:
+                            type: object
+                            title: Identity Server Domain Signature
+                            description: The signature for the identity server.
+                            properties:
+                              "ed25519:0":
+                                type: string
+                                description: The signature.
+                                example: "SomeSignatureGoesHere"
+                            required: ['ed25519:0']
+                          example: {
+                            "vector.im": {
+                              "ed25519:0": "SomeSignatureGoesHere"
+                            }
+                          }
+                      required: ['mxid', 'token', 'signatures']
+                  required:
+                    - medium
+                    - address
+                    - mxid
+                    - room_id
+                    - sender
+                    - signed
+            required: ['medium', 'address', 'mxid', 'invites']
+      responses:
+        200:
+          description: The homeserver has processed the notification.
+          examples:
+            application/json: {}
+          schema:
+            type: object
+            description: An empty object
+            example: {}

api/server-server/transactions.yaml

@@ -60,8 +60,8 @@ paths:
                   edus:
                     type: array
                     description: |-
-                      List of ephemeral messages. May be omitted if there are no ephemeral 
+                      List of ephemeral messages. May be omitted if there are no ephemeral
-                      messages to be sent.
+                      messages to be sent. Must not include more than 100 EDUs.
                     items:
                       $ref: "definitions/edu.yaml"
           example: {

api/server-server/user_keys.yaml

@@ -0,0 +1,189 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation User Key Management API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/user/keys/claim":
+    post:
+      summary: Claims one-time encryption keys for a user.
+      description: |-
+        Claims one-time keys for use in pre-key messages.
+      operationId: claimUserEncryptionKeys
+      security:
+        - signedRequest: []
+      parameters:
+        - in: body
+          name: body
+          type: object
+          required: true
+          schema:
+            type: object
+            properties:
+              one_time_keys:
+                type: object
+                description: |-
+                  The keys to be claimed. A map from user ID, to a map from
+                  device ID to algorithm name.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    type: string
+                    description: algorithm
+                    example: "signed_curve25519"
+                example: {
+                  "@alice:example.com": {
+                    "JLAFKJWSCS": "signed_curve25519"
+                  }
+                }
+            required:
+              - one_time_keys
+      responses:
+        200:
+          description: The claimed keys
+          schema:
+            type: object
+            properties:
+              one_time_keys:
+                type: object
+                description: |-
+                  One-time keys for the queried devices. A map from user ID, to a
+                  map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    type:
+                      - string
+                      - object
+            required: ['one_time_keys']
+          examples:
+            application/json: {
+              "one_time_keys": {
+                "@alice:example.com": {
+                  "JLAFKJWSCS": {
+                    "signed_curve25518:AAAAHg": {
+                      "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                      "signatures": {
+                        "@alice:example.com": {
+                          "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+  "/user/keys/query":
+    post:
+      summary: Download device identity keys.
+      description: |-
+        Returns the current devices and identity keys for the given users.
+      operationId: queryUserEncryptionKeys
+      security:
+        - signedRequest: []
+      parameters:
+        - in: body
+          name: body
+          type: object
+          required: true
+          schema:
+            type: object
+            properties:
+              device_keys:
+                type: object
+                description: |-
+                  The keys to be downloaded. A map from user ID, to a list of
+                  device IDs, or to an empty list to indicate all devices for the
+                  corresponding user.
+                additionalProperties:
+                  type: array
+                  items:
+                    type: string
+                    description: "Device ID"
+                example: {
+                  "@alice:example.com": []
+                }
+            required: ['device_keys']
+      responses:
+        200:
+          description: The device information.
+          schema:
+            type: object
+            properties:
+              device_keys:
+                type: object
+                description: |-
+                  Information on the queried devices. A map from user ID, to a
+                  map from device ID to device information.  For each device,
+                  the information returned will be the same as uploaded via
+                  ``/keys/upload``, with the addition of an ``unsigned``
+                  property.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    allOf:
+                      - $ref: ../client-server/definitions/device_keys.yaml
+                    properties:
+                      unsigned:
+                        title: UnsignedDeviceInfo
+                        type: object
+                        description: |-
+                          Additional data added to the device key information
+                          by intermediate servers, and not covered by the
+                          signatures.
+                        properties:
+                          device_display_name:
+                            type: string
+                            description:
+                              The display name which the user set on the device.
+            required: ['device_keys']
+          examples:
+            application/json: {
+              "device_keys": {
+                "@alice:example.com": {
+                  "JLAFKJWSCS": {
+                    "user_id": "@alice:example.com",
+                    "device_id": "JLAFKJWSCS",
+                    "algorithms": [
+                      "m.olm.v1.curve25519-aes-sha256",
+                      "m.megolm.v1.aes-sha"
+                    ],
+                    "keys": {
+                      "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
+                      "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
+                    },
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
+                      }
+                    },
+                    "unsigned": {
+                      "device_display_name": "Alice's mobile phone"
+                    }
+                  }
+                }
+              }
+            }

changelogs/application_service.rst

@@ -0,0 +1,7 @@
+r0.1.0
+======
+
+This is the first release of the Application Service specification. It
+includes support for application services being able to interact with
+homeservers and bridge third party networks, such as IRC, over to Matrix
+in a standard and accessible way.

changelogs/application_service/newsfragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelogs/application_service/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../application_service.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true

changelogs/client_server/newsfragments/1176.new

@@ -0,0 +1 @@
+Specify how to control the power level required for ``@room``

changelogs/client_server/newsfragments/1359.feature

@@ -0,0 +1 @@
+Add ``.well-known`` server discovery method

changelogs/client_server/newsfragments/1465.feature

@@ -0,0 +1 @@
+Share room decryption keys between devices

changelogs/client_server/newsfragments/1547.feature

@@ -0,0 +1 @@
+Add a common standard for user, room, and group mentions in messages.

changelogs/client_server/newsfragments/1550.feature

@@ -0,0 +1 @@
+Add server ACLs as an option for controlling federation in a room.

changelogs/client_server/newsfragments/1551.clarification

@@ -0,0 +1 @@
+Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match.

changelogs/client_server/newsfragments/1551.feature

@@ -0,0 +1 @@
+Add new push rules for encrypted events and ``@room`` notifications.

changelogs/client_server/newsfragments/1554.feature

@@ -0,0 +1 @@
+Add third party network room directories, as provided by application services.

changelogs/client_server/newsfragments/1558.clarification

@@ -0,0 +1 @@
+Update all event examples to be accurate representations of their associated events.

changelogs/client_server/newsfragments/1562.clarification

@@ -0,0 +1 @@
+Clarify the supported HTML features for room messages.

changelogs/client_server/newsfragments/1567.feature

@@ -0,0 +1 @@
+Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``.

changelogs/client_server/newsfragments/1567.new

@@ -0,0 +1 @@
+Add ``POST /account/3pid/delete``

changelogs/client_server/newsfragments/1568.clarification

@@ -0,0 +1 @@
+Move the ``invite_room_state`` definition under ``unsigned`` where it actually resides.

changelogs/client_server/newsfragments/1569.clarification

@@ -0,0 +1 @@
+Clarify the homeserver's behaviour for searching users.

changelogs/client_server/newsfragments/1570.clarification

@@ -0,0 +1 @@
+Clarify the object structures and defaults for Filters.

changelogs/client_server/newsfragments/1571.clarification

@@ -0,0 +1 @@
+Clarify instances of ``type: number`` in the swagger/OpenAPI schema definitions.

changelogs/client_server/newsfragments/1572.clarification

@@ -0,0 +1 @@
+Clarify that left rooms also have account data in ``/sync``.

changelogs/client_server/newsfragments/1574.clarification

@@ -0,0 +1 @@
+Fix naming of the body field in ``PUT /directory/room``.

changelogs/client_server/newsfragments/1577.clarification

@@ -0,0 +1 @@
+Clarify the filter object schema used in room searching.

changelogs/client_server/newsfragments/1589.feature

@@ -0,0 +1 @@
+Add an ``inhibit_login`` registration option.

changelogs/client_server/newsfragments/1590.clarification

@@ -0,0 +1 @@
+Document the 403 error for sending state events.

changelogs/client_server/newsfragments/1596.clarification

@@ -0,0 +1 @@
+specify how to handle multiple olm sessions with the same device

changelogs/client_server/newsfragments/1600.feature

@@ -0,0 +1 @@
+Recommend that servers set a Content Security Policy for the content repository.

changelogs/client_server/newsfragments/1602.clarification

@@ -0,0 +1 @@
+Add the other keys that redactions are expected to preserve.

changelogs/client_server/newsfragments/1605.clarification

@@ -0,0 +1 @@
+Clarify that clients should not be generating invalid HTML for formatted events.

changelogs/client_server/newsfragments/1606.clarification

@@ -0,0 +1 @@
+Clarify the room tag structure (thanks @KitsuneRal!)

changelogs/client_server/newsfragments/780.feature

@@ -0,0 +1 @@
+Add more presence options to the ``set_presence`` parameter of ``/sync``. (Thanks @mujx!)

changelogs/identity_service/newsfragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelogs/identity_service/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../identity_service.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true

changelogs/push_gateway.rst

@@ -0,0 +1,6 @@
+r0.1.0
+======
+
+The first release of the Push Gateway specification. This release contains
+a single endpoint, ``/notify``, that pushers may use to send push notifications
+to clients.

changelogs/push_gateway/newsfragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelogs/push_gateway/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../push_gateway.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true

changelogs/server_server/newsfragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelogs/server_server/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../server_server.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true

event-schemas/check_examples.py

@@ -44,16 +44,51 @@ except ImportError as e:
     raise
 
 
+def load_file(path):
+    print("Loading reference: %s" % path)
+    if not path.startswith("file://"):
+        raise Exception("Bad ref: %s" % (path,))
+    path = path[len("file://"):]
+    with open(path, "r") as f:
+        if path.endswith(".json"):
+            return json.load(f)
+        else:
+            # We have to assume it's YAML because some of the YAML examples
+            # do not have file extensions.
+            return yaml.load(f)
+
+
+def resolve_references(path, schema):
+    if isinstance(schema, dict):
+        # do $ref first
+        if '$ref' in schema:
+            value = schema['$ref']
+            path = os.path.abspath(os.path.join(os.path.dirname(path), value))
+            ref = load_file("file://" + path)
+            result = resolve_references(path, ref)
+            del schema['$ref']
+        else:
+            result = {}
+
+        for key, value in schema.items():
+            result[key] = resolve_references(path, value)
+        return result
+    elif isinstance(schema, list):
+        return [resolve_references(path, value) for value in schema]
+    else:
+        return schema
+
+
 def check_example_file(examplepath, schemapath):
     with open(examplepath) as f:
-        example = yaml.load(f)
+        example = resolve_references(examplepath, json.load(f))
 
     with open(schemapath) as f:
         schema = yaml.load(f)
 
     fileurl = "file://" + os.path.abspath(schemapath)
     schema["id"] = fileurl
-    resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_yaml})
+    resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_file})
 
     print ("Checking schema for: %r %r" % (examplepath, schemapath))
     try:
@@ -71,6 +106,10 @@ def check_example_dir(exampledir, schemadir):
             if filename.startswith("."):
                 # Skip over any vim .swp files.
                 continue
+            cwd = os.path.basename(os.path.dirname(os.path.join(root, filename)))
+            if cwd == "core":
+                # Skip checking the underlying definitions
+                continue
             examplepath = os.path.join(root, filename)
             schemapath = examplepath.replace(exampledir, schemadir)
             if schemapath.find("#") >= 0:
@@ -85,14 +124,6 @@ def check_example_dir(exampledir, schemadir):
         raise ValueError("Error validating examples")
 
 
-def load_yaml(path):
-    if not path.startswith("file:///"):
-        raise Exception("Bad ref: %s" % (path,))
-    path = path[len("file://"):]
-    with open(path, "r") as f:
-        return yaml.load(f)
-
-
 if __name__ == '__main__':
     try:
         check_example_dir("examples", "schema")

event-schemas/examples/core/event.json

@@ -0,0 +1,6 @@
+{
+    "content": {
+        "key": "value"
+    },
+    "type": "org.example.custom.event"
+}

event-schemas/examples/core/room_edu.json

@@ -0,0 +1,4 @@
+{
+    "$ref": "event.json",
+    "room_id": "!jEsUZKDJdhlrceRyVU:domain.com"
+}

event-schemas/examples/core/room_event.json

@@ -0,0 +1,10 @@
+{
+    "$ref": "event.json",
+    "event_id": "$143273582443PhrSn:domain.com",
+    "room_id": "!jEsUZKDJdhlrceRyVU:domain.com",
+    "sender": "@example:domain.com",
+    "origin_server_ts": 1432735824653,
+    "unsigned": {
+      "age": 1234
+    }
+}

event-schemas/examples/core/state_event.json

@@ -0,0 +1,4 @@
+{
+    "$ref": "room_event.json",
+    "state_key": "ArbitraryString"
+}

event-schemas/examples/m.call.answer

@@ -1,5 +1,6 @@
 {
-  "age": 242352,
+  "$ref": "core/room_event.json",
+  "type": "m.call.answer",
   "content": {
     "version" : 0,
     "call_id": "12345",
@@ -8,10 +9,5 @@
       "type" : "answer",
       "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
     }
-  },
+  }
-  "origin_server_ts": 1431961217939,
-  "event_id": "$WLGTSEFSEF:localhost",
-  "type": "m.call.answer",
-  "room_id": "!Cuyf34gef24t:localhost",
-  "sender": "@example:localhost"
 }

event-schemas/examples/m.call.candidates

@@ -1,5 +1,6 @@
 {
-  "age": 242352,
+  "$ref": "core/room_event.json",
+  "type": "m.call.candidates",
   "content": {
     "version" : 0,
     "call_id": "12345",
@@ -10,10 +11,5 @@
         "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0"
       }
     ]
-  },
+  }
-  "origin_server_ts": 1431961217939,
-  "event_id": "$WLGTSEFSEF:localhost",
-  "type": "m.call.candidates",
-  "room_id": "!Cuyf34gef24t:localhost",
-  "sender": "@example:localhost"
 }

event-schemas/examples/m.call.hangup

@@ -1,12 +1,8 @@
 {
-  "age": 242352,
+  "$ref": "core/room_event.json",
+  "type": "m.call.hangup",
   "content": {
     "version" : 0,
     "call_id": "12345"
-  },
+  }
-  "origin_server_ts": 1431961217939,
-  "event_id": "$WLGTSEFSEF:localhost",
-  "type": "m.call.hangup",
-  "room_id": "!Cuyf34gef24t:localhost",
-  "sender": "@example:localhost"
 }

event-schemas/examples/m.call.invite

@@ -1,5 +1,6 @@
 {
-  "age": 242352,
+  "$ref": "core/room_event.json",
+  "type": "m.call.invite",
   "content": {
     "version" : 0,
     "call_id": "12345",
@@ -8,10 +9,5 @@
       "type" : "offer",
       "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
     }
-  },
+  }
-  "origin_server_ts": 1431961217939,
-  "event_id": "$WLGTSEFSEF:localhost",
-  "type": "m.call.invite",
-  "room_id": "!Cuyf34gef24t:localhost",
-  "sender": "@example:localhost"
 }

event-schemas/examples/m.direct

@@ -1,9 +1,10 @@
 {
+  "$ref": "core/event.json",
   "type": "m.direct",
   "content": {
     "@bob:example.com": [
-        "!abcdefgh:example.com",
+      "!abcdefgh:example.com",
-        "!hgfedcba:example.com"
+      "!hgfedcba:example.com"
-      ]
+    ]
   }
 }

event-schemas/examples/m.forwarded_room_key

@@ -0,0 +1,14 @@
+{
+  "content": {
+    "algorithm": "m.megolm.v1.aes-sha2",
+    "room_id": "!Cuyf34gef24t:localhost",
+    "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
+    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...",
+    "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
+    "sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
+    "forwarding_curve25519_key_chain": [
+      "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
+    ]
+  },
+  "type": "m.forwarded_room_key"
+}

event-schemas/examples/m.ignored_user_list

@@ -1,4 +1,5 @@
 {
+  "$ref": "core/event.json",
   "type": "m.ignored_user_list",
   "content": {
     "ignored_users": {