Merge branch 'master' into matthew/msc1779

.buildkite/pipeline.yaml

@@ -0,0 +1,16 @@
+steps:
+  - label: ":books: Build spec"
+    command:
+      - python3 -m venv env
+      - env/bin/pip install -r scripts/requirements.txt
+      - ". env/bin/activate; scripts/generate-matrix-org-assets"
+    artifact_paths:
+      - assets.tar.gz
+    plugins:
+      - docker#v3.0.1:
+          image: "python:3.6"
+
+  - label: "rebuild matrix.org"
+    trigger: "matrix-dot-org"
+    async: true
+    branches: "master"

CONTRIBUTING.rst

@@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a
 server before they can be documented in the specification. This process can take
 some time to complete.
 
-For this reason, we have not found the github pull-request model effective for
+Changes to the protocol (new endpoints, ideas, etc) need to go through the
-discussing changes to the specification. Instead, we have adopted the workflow
+`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
-as described at https://matrix.org/docs/spec/proposals - *please read this for
+such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
-details on how to contribute spec changes*.
+If you're not sure, visit us at `#matrix-spec:matrix.org`_
+and ask.
 
 
 Other changes
@@ -51,8 +52,7 @@ following:
   <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
 
   (If there is any doubt about whether it is the spec or the implementations
-  that need fixing, please discuss it with us first in `#matrix-dev:matrix.org
+  that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
-  <http://matrix.to/#/#matrix-dev:matrix.org>`_.)
 
 * Clarifications to the specification which do not change the behaviour of
   Matrix servers or clients in a way which might introduce compatibility
@@ -60,14 +60,16 @@ following:
   `clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
   label.
 
-  For example, recommendations for UI behaviour do not require a proposal
+  For example, areas where the specification is unclear do not require a proposal
-  document. On the other hand, changes to event contents would be best
+  to fix. On the other hand, introducing new behaviour is best represented by a
-  discussed in a proposal document even though no changes would be necessary to
+  proposal.
-  server implementations.
 
-For such changes, please do just open a `pull request`_.
+For such changes, please do just open a `pull request`_. If you're not sure if
+your change is covered by the above, please visit `#matrix-spec:matrix.org` and
+ask.
 
-.. _pull request: https://help.github.com/articles/about-pull-requests
+.. _`pull request`: https://help.github.com/articles/about-pull-requests
+.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
 
 
 Adding to the changelog
@@ -96,7 +98,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``breaking`` - Used when the change is not backwards compatible.
 
-* ``deprecation`` - Used when deprecating something
+* ``deprecation`` - Used when deprecating something.
 
 All news fragments must have a brief summary explaining the change in the
 contents of the file. The summary must end in a full stop to be in line with

api/application-service/transactions.yaml

@@ -56,7 +56,7 @@ paths:
             example: {
               "events": [
                 {"$ref": "../../event-schemas/examples/m.room.member"},
-                {"$ref": "../../event-schemas/examples/m.room.message#m.text"}
+                {"$ref": "../../event-schemas/examples/m.room.message$m.text"}
               ]
             }
             description: Transaction information

api/client-server/administrative_contact.yaml

@@ -163,6 +163,14 @@ paths:
           schema:
             type: object
             properties:
+              id_server:
+                type: string
+                description: |-
+                    The identity server to unbind from. If not provided, the homeserver
+                    MUST use the ``id_server`` the identifier was added through. If the
+                    homeserver does not know the original ``id_server``, it MUST return
+                    a ``id_server_unbind_result`` of ``no-support``.
+                example: "example.org"
               medium:
                 type: string
                 description: The medium of the third party identifier being removed.
@@ -180,7 +188,24 @@ paths:
             user.
           schema:
             type: object
-            properties: {}
+            properties:
+              id_server_unbind_result:
+                type: string
+                enum:
+                  # XXX: I don't know why, but the order matters here so that "no-support"
+                  # doesn't become "no- support" by the renderer.
+                  - "no-support"
+                  - "success"
+                description: |-
+                  An indicator as to whether or not the homeserver was able to unbind
+                  the 3PID from the identity server. ``success`` indicates that the
+                  indentity server has unbound the identifier whereas ``no-support``
+                  indicates that the identity server refuses to support the request
+                  or the homeserver was not able to determine an identity server to
+                  unbind from.
+                example: "success"
+            required:
+              - id_server_unbind_result
       tags:
         - User data
   "/account/3pid/email/requestToken":

api/client-server/content-repo.yaml

@@ -41,7 +41,7 @@ paths:
           name: Content-Type
           type: string
           description: The content type of the file being uploaded
-          x-example: "Content-Type: audio/mpeg"
+          x-example: "Content-Type: application/pdf"
         - in: query
           type: string
           x-example: "War and Peace.pdf"
@@ -51,6 +51,7 @@ paths:
           name: "<content>"
           description: The content to be uploaded.
           required: true
+          x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
           schema:
             type: string
             example: "<bytes>"
@@ -103,7 +104,7 @@ paths:
           default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to 
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
             true if not provided.
       responses:
         200:
@@ -158,7 +159,7 @@ paths:
           default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to 
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
             true if not provided.
       responses:
         200:
@@ -202,6 +203,7 @@ paths:
           type: integer
           x-example: 64
           name: width
+          required: true
           description: |-
             The *desired* width of the thumbnail. The actual thumbnail may not
             match the size specified.
@@ -209,6 +211,7 @@ paths:
           type: integer
           x-example: 64
           name: height
+          required: true
           description: |-
             The *desired* height of the thumbnail. The actual thumbnail may not
             match the size specified.
@@ -226,7 +229,7 @@ paths:
           default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to 
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
             true if not provided.
       responses:
         200:
@@ -328,7 +331,7 @@ paths:
               m.upload.size:
                 type: integer
                 format: int64
-                description: |- 
+                description: |-
                   The maximum size an upload can be in bytes.
                   Clients SHOULD use this as a guide when uploading content.
                   If not listed or null, the size limit should be treated as unknown.

api/client-server/definitions/push_condition.yaml

@@ -16,16 +16,20 @@ title: PushCondition
 type: object
 properties:
   kind:
-    enum:
-    - event_match
-    - contains_display_name
-    - room_member_count
     type: string
+    description: |-
+      The kind of condition to apply. See `conditions <#conditions>`_ for
+      more information on the allowed kinds and how they work.
   key:
     type: string
     description: |-
       Required for ``event_match`` conditions. The dot-separated field of the
       event to match.
+
+      Required for ``sender_notification_permission`` conditions. The field in
+      the power level event the user needs a minimum power level for. Fields
+      must be specified under the ``notifications`` property in the power level
+      event's ``content``.
     x-example: content.body
   pattern:
     type: string

api/client-server/definitions/third_party_signed.yaml

@@ -0,0 +1,41 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# 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.
+type: object
+title: Third Party Signed
+description: |-
+  A signature of an ``m.third_party_invite`` token to prove that this user
+  owns a third party identity which has been invited to the room.
+properties:
+  sender:
+    type: string
+    description: The Matrix ID of the user who issued the invite.
+    example: "@alice:example.org"
+  mxid:
+    type: string
+    description: The Matrix ID of the invitee.
+    example: "@bob:example.org"
+  token:
+    type: string
+    description: The state key of the m.third_party_invite event.
+    example: "random8nonce"
+  signatures:
+    type: object
+    description: A signatures object containing a signature of the entire signed object.
+    title: Signatures
+    example: {
+      "example.org": {
+        "ed25519:0": "some9signature"
+      }
+    }
+required: ["sender", "mxid", "token", "signatures"]

api/client-server/directory.yaml

@@ -148,5 +148,14 @@ paths:
               }
           schema:
             type: object
+        404:
+          description: There is no mapped room ID for this room alias.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "Room alias #monkeys:example.org not found."
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory

api/client-server/event_context.yaml

@@ -101,65 +101,35 @@ paths:
                     - "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
           examples:
             application/json: {
-                  "end": "t29-57_2_0_2",
+              "end": "t29-57_2_0_2",
-                  "events_after": [
+              "events_after": [
-                    {
+                {
-                      "age": 91911336,
+                  "room_id": "!636q39766251:example.com",
-                      "content": {
+                  "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                        "body": "7",
-                        "msgtype": "m.text"
-                      },
-                      "event_id": "$14460306086CiUaL:localhost:8480",
-                      "origin_server_ts": 1446030608551,
-                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
-                      "type": "m.room.message",
-                      "sender": "@test:localhost:8480"
-                    }
-                  ],
-                  "events_before": [
-                    {
-                      "age": 91911903,
-                      "content": {
-                        "body": "5",
-                        "msgtype": "m.text"
-                      },
-                      "event_id": "$14460306074UYTlh:localhost:8480",
-                      "origin_server_ts": 1446030607984,
-                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
-                      "type": "m.room.message",
-                      "sender": "@test:localhost:8480"
-                    }
-                  ],
-                  "start": "t27-54_2_0_2",
-                  "state": [
-                    {
-                      "age": 3123715284,
-                      "content": {
-                        "creator": "@test:localhost:8480"
-                      },
-                      "event_id": "$14429988040dgQAE:localhost:8480",
-                      "origin_server_ts": 1442998804603,
-                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
-                      "state_key": "",
-                      "type": "m.room.create",
-                      "sender": "@test:localhost:8480"
-                    },
-                    {
-                      "age": 2067105053,
-                      "content": {
-                        "avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto",
-                        "displayname": "Bob2",
-                        "membership": "join"
-                      },
-                      "event_id": "$14440554144URDbf:localhost:8480",
-                      "origin_server_ts": 1444055414834,
-                      "replaces_state": "$14440552472PgiGk:localhost:8480",
-                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
-                      "state_key": "@test:localhost:8480",
-                      "type": "m.room.member",
-                      "sender": "@test:localhost:8480"
-                    }
-                  ]
                 }
+              ],
+              "event": {
+                "event_id": "$f3h4d129462ha:example.com",
+                "room_id": "!636q39766251:example.com",
+                "$ref": "definitions/event-schemas/examples/m.room.message$m.image"
+              },
+              "events_before": [
+                {
+                  "room_id": "!636q39766251:example.com",
+                  "$ref": "definitions/event-schemas/examples/m.room.message$m.file"
+                }
+              ],
+              "start": "t27-54_2_0_2",
+              "state": [
+                {
+                  "room_id": "!636q39766251:example.com",
+                  "$ref": "definitions/event-schemas/examples/m.room.create"
+                },
+                {
+                  "room_id": "!636q39766251:example.com",
+                  "$ref": "definitions/event-schemas/examples/m.room.member"
+                }
+              ]
+            }
       tags:
         - Room participation

api/client-server/joining.yaml

@@ -58,38 +58,9 @@ paths:
           name: third_party_signed
           schema:
             type: object
-            example: {
-                "third_party_signed": {
-                  "sender": "@cat:the.hat",
-                  "mxid": "@green:eggs.ham",
-                  "token": "random8nonce",
-                  "signatures": {
-                    "horton.hears": {
-                      "ed25519:0": "some9signature"
-                    }
-                  }
-                }
-              }
             properties:
               third_party_signed:
-                type: object
+                $ref: "definitions/third_party_signed.yaml"
-                title: ThirdPartySigned
-                description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
-                properties:
-                  sender:
-                    type: string
-                    description: The Matrix ID of the user who issued the invite.
-                  mxid:
-                    type: string
-                    description: The Matrix ID of the invitee.
-                  token:
-                    type: string
-                    description: The state key of the m.third_party_invite event.
-                  signatures:
-                    type: object
-                    description: A signatures object containing a signature of the entire signed object.
-                    title: Signatures
-                required: ["sender", "mxid", "token", "signatures"]
       responses:
         200:
           description: |-
@@ -163,45 +134,9 @@ paths:
           name: third_party_signed
           schema:
             type: object
-            example: {
-                "third_party_signed": {
-                  "signed": {
-                    "sender": "@cat:the.hat",
-                    "mxid": "@green:eggs.ham",
-                    "token": "random8nonce",
-                    "signatures": {
-                      "horton.hears": {
-                        "ed25519:0": "some9signature"
-                      }
-                    }
-                  }
-                }
-              }
             properties:
               third_party_signed:
-                type: object
+                $ref: "definitions/third_party_signed.yaml"
-                title: ThirdPartySigned
-                description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
-                properties:
-                  signed:
-                    type: object
-                    title: Signed
-                    properties:
-                      sender:
-                        type: string
-                        description: The Matrix ID of the user who issued the invite.
-                      mxid:
-                        type: string
-                        description: The Matrix ID of the invitee.
-                      token:
-                        type: string
-                        description: The state key of the m.third_party_invite event.
-                      signatures:
-                        type: object
-                        description: A signatures object containing a signature of the entire signed object.
-                        title: Signatures
-                    required: ["sender", "mxid", "token", "signatures"]
-                required: ["signed"]
       responses:
         200:
           description: |-

api/client-server/keys.yaml

@@ -253,7 +253,7 @@ paths:
       responses:
         200:
           description:
-            The claimed keys
+            The claimed keys.
           schema:
             type: object
             properties:

api/client-server/logout.yaml

@@ -32,7 +32,8 @@ paths:
       summary: Invalidates a user access token
       description: |-
         Invalidates an existing access token, so that it can no longer be used for
-        authorization.
+        authorization. The device associated with the access token is also deleted.
+        `Device keys <#device-keys>`_ for the device are deleted alongside the device.
       operationId: logout
       security:
         - accessToken: []
@@ -49,7 +50,9 @@ paths:
       summary: Invalidates all access tokens for a user
       description: |-
         Invalidates all access tokens for a user, so that they can no longer be used for
-        authorization. This includes the access token that made this request. 
+        authorization. This includes the access token that made this request. All devices
+        for the user are also deleted. `Device keys <#device-keys>`_ for the device are
+        deleted alongside the device.
 
         This endpoint does not require UI authorization because UI authorization is
         designed to protect against attacks where the someone gets hold of a single access

api/client-server/message_pagination.yaml

@@ -103,7 +103,10 @@ paths:
               chunk:
                 type: array
                 description: |-
-                  A list of room events.
+                  A list of room events. The order depends on the ``dir`` parameter.
+                  For ``dir=b`` events will be in reverse-chronological order,
+                  for ``dir=f`` in chronological order, so that events start
+                  at the ``from`` point.
                 items:
                   type: object
                   title: RoomEvent
@@ -114,43 +117,16 @@ paths:
                 "end": "t47409-4357353_219380_26003_2265",
                 "chunk": [
                   {
-                    "origin_server_ts": 1444812213737,
+                    "room_id": "!636q39766251:example.com",
-                    "sender": "@alice:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                    "event_id": "$1444812213350496Caaaa:example.com",
-                    "content": {
-                      "body": "hello world",
-                      "msgtype":"m.text"
-                    },
-                    "room_id":"!Xq3620DUiqCaoxq:example.com",
-                    "type":"m.room.message",
-                    "age": 1042
                   },
                   {
-                    "origin_server_ts": 1444812194656 ,
+                    "room_id": "!636q39766251:example.com",
-                    "sender": "@bob:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.name"
-                    "event_id": "$1444812213350496Cbbbb:example.com",
-                    "content": {
-                      "body": "the world is big",
-                      "msgtype":"m.text"
-                    },
-                    "room_id":"!Xq3620DUiqCaoxq:example.com",
-                    "type":"m.room.message",
-                    "age": 20123
                   },
                   {
-                    "origin_server_ts": 1444812163990,
+                    "room_id": "!636q39766251:example.com",
-                    "sender": "@bob:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.message$m.video"
-                    "event_id": "$1444812213350496Ccccc:example.com",
-                    "content": {
-                      "name": "New room name"
-                    },
-                    "prev_content": {
-                      "name": "Old room name"
-                    },
-                    "state_key": "",
-                    "room_id":"!Xq3620DUiqCaoxq:example.com",
-                    "type":"m.room.name",
-                    "age": 50789
                   }
                 ]
               }

api/client-server/notifications.yaml

@@ -75,16 +75,7 @@ paths:
                     "room_id": "!abcdefg:example.com",
                     "ts": 1475508881945,
                     "event": {
-                      "sender": "@alice:example.com",
+                      "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                      "type": "m.room.message",
-                      "age": 124524,
-                      "txn_id": "1234",
-                      "content": {
-                        "body": "I am a fish",
-                        "msgtype": "m.text"
-                      },
-                      "origin_server_ts": 1417731086797,
-                      "event_id": "$74686972643033:example.com"
                     }
                   }
                 ]

api/client-server/old_sync.yaml

@@ -64,18 +64,7 @@ paths:
                 "start": "s3456_9_0",
                 "end": "s3457_9_0",
                 "chunk": [
-                  {
+                  {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
-                    "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",
-                    "sender": "@bob:localhost"
-                  }
                 ]
               }
           schema:
@@ -142,16 +131,7 @@ paths:
             application/json: {
                   "end": "s3456_9_0",
                   "presence": [
-                      {
+                      {"$ref": "definitions/event-schemas/examples/m.presence"}
-                          "content": {
-                              "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                              "displayname": "Bob",
-                              "last_active_ago": 31053,
-                              "presence": "online",
-                              "user_id": "@bob:localhost"
-                          },
-                          "type": "m.presence"
-                      }
                   ],
                   "account_data": [
                     {
@@ -167,28 +147,12 @@ paths:
                           "messages": {
                               "chunk": [
                                   {
-                                      "age": 343513403,
+                                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                      "content": {
+                                    "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                                          "body": "foo",
-                                          "msgtype": "m.text"
-                                      },
-                                      "event_id": "$14328044851tzTJS:localhost",
-                                      "origin_server_ts": 1432804485886,
-                                      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                      "type": "m.room.message",
-                                      "sender": "@alice:localhost"
                                   },
                                   {
-                                      "age": 343511809,
+                                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                      "content": {
+                                    "$ref": "definitions/event-schemas/examples/m.room.message$m.video"
-                                          "body": "bar",
-                                          "msgtype": "m.text"
-                                      },
-                                      "event_id": "$14328044872spjFg:localhost",
-                                      "origin_server_ts": 1432804487480,
-                                      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                      "type": "m.room.message",
-                                      "sender": "@bob:localhost"
                                   }
                               ],
                               "end": "s3456_9_0",
@@ -197,81 +161,20 @@ paths:
                           "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                           "state": [
                               {
-                                  "age": 7148266897,
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "content": {
+                                "$ref": "definitions/event-schemas/examples/m.room.join_rules"
-                                      "join_rule": "public"
-                                  },
-                                  "event_id": "$14259997323TLwtb:localhost",
-                                  "origin_server_ts": 1425999732392,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "",
-                                  "type": "m.room.join_rules",
-                                  "sender": "@alice:localhost"
                               },
                               {
-                                  "age": 6547561012,
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "content": {
+                                "$ref": "definitions/event-schemas/examples/m.room.member"
-                                      "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                                      "membership": "join"
-                                  },
-                                  "event_id": "$1426600438280zExKY:localhost",
-                                  "membership": "join",
-                                  "origin_server_ts": 1426600438277,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "@alice:localhost",
-                                  "type": "m.room.member",
-                                  "sender": "@alice:localhost"
                               },
                               {
-                                  "age": 7148267200,
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "content": {
+                                "$ref": "definitions/event-schemas/examples/m.room.create"
-                                      "creator": "@alice:localhost"
-                                  },
-                                  "event_id": "$14259997320KhbwJ:localhost",
-                                  "origin_server_ts": 1425999732089,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "",
-                                  "type": "m.room.create",
-                                  "sender": "@alice:localhost"
                               },
                               {
-                                  "age": 1622568720,
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "content": {
+                                "$ref": "definitions/event-schemas/examples/m.room.power_levels"
-                                      "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                                      "displayname": "Bob",
-                                      "membership": "join"
-                                  },
-                                  "event_id": "$1431525430134MxlLX:localhost",
-                                  "origin_server_ts": 1431525430569,
-                                  "replaces_state": "$142652023736BSXcM:localhost",
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "@bob:localhost",
-                                  "type": "m.room.member",
-                                  "sender": "@bob:localhost"
-                              },
-                              {
-                                  "age": 7148267004,
-                                  "content": {
-                                      "ban": 50,
-                                      "events": {
-                                          "m.room.name": 100,
-                                          "m.room.power_levels": 100
-                                      },
-                                      "events_default": 0,
-                                      "kick": 50,
-                                      "redact": 50,
-                                      "state_default": 50,
-                                      "users": {
-                                          "@alice:localhost": 100
-                                      },
-                                      "users_default": 0
-                                  },
-                                  "event_id": "$14259997322mqfaq:localhost",
-                                  "origin_server_ts": 1425999732285,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "",
-                                  "type": "m.room.power_levels",
-                                  "sender": "@alice:localhost"
                               }
                           ],
                           "visibility": "private",
@@ -423,16 +326,7 @@ paths:
         200:
           description: The full event.
           examples:
-            application/json: {
+            application/json: {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
-                "content": {
-                  "body": "Hello world!",
-                  "msgtype": "m.text"
-                },
-                "room_id": "!wfgy43Sg4a:matrix.org",
-                "sender": "@bob:matrix.org",
-                "event_id": "$asfDuShaf7Gafaw:matrix.org",
-                "type": "m.room.message"
-              }
           schema:
             allOf:
               - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"

api/client-server/peeking_events.yaml

@@ -75,16 +75,8 @@ paths:
                 "end": "s3457_9_0",
                 "chunk": [
                   {
-                    "age": 32,
+                    "room_id": "!somewhere:over.the.rainbow",
-                    "content": {
+                    "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                        "body": "incoming message",
-                        "msgtype": "m.text"
-                    },
-                    "event_id": "$14328055551tzaee:localhost",
-                    "origin_server_ts": 1432804485886,
-                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                    "type": "m.room.message",
-                    "sender": "@bob:localhost"
                   }
                 ]
               }

api/client-server/registration.yaml

@@ -29,7 +29,8 @@ paths:
     post:
       summary: Register for an account on this homeserver.
       description: |-
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the `User-Interactive Authentication API`_, except in
+        the cases where a guest account is being registered.
 
         Register for an account on this homeserver.
 
@@ -59,6 +60,11 @@ paths:
         supplied by the client or generated by the server. The server may
         invalidate any access token previously associated with that device. See
         `Relationship between access tokens and devices`_.
+
+        When registering a guest account, all parameters in the request body
+        with the exception of ``initial_device_display_name`` MUST BE ignored
+        by the server. The server MUST pick a ``device_id`` for the account
+        regardless of input.
       operationId: register
       parameters:
         - in: query
@@ -72,7 +78,7 @@ paths:
           enum:
             - guest
             - user
-          description: The kind of account to register. Defaults to `user`.
+          description: The kind of account to register. Defaults to ``user``.
         - in: body
           name: body
           schema:
@@ -80,13 +86,11 @@ paths:
             properties:
               auth:
                 description: |-
-                    Additional authentication information for the
+                  Additional authentication information for the
-                    user-interactive authentication API. Note that this
+                  user-interactive authentication API. Note that this
-                    information is *not* used to define how the registered user
+                  information is *not* used to define how the registered user
-                    should be authenticated, but is instead used to
+                  should be authenticated, but is instead used to
-                    authenticate the ``register`` call itself. It should be
+                  authenticate the ``register`` call itself.
-                    left empty, or omitted, unless an earlier call returned an
-                    response with status code 401.
                 "$ref": "definitions/auth_data.yaml"
               bind_email:
                 type: boolean
@@ -94,6 +98,12 @@ paths:
                   If true, the server binds the email used for authentication to
                   the Matrix ID with the identity server.
                 example: false
+              bind_msisdn:
+                type: boolean
+                description: |-
+                  If true, the server binds the phone number used for authentication
+                  to the Matrix ID with the identity server.
+                example: false
               username:
                 type: string
                 description: |-
@@ -194,6 +204,18 @@ paths:
             The homeserver requires additional authentication information.
           schema:
             "$ref": "definitions/auth_response.yaml"
+        403:
+          description: |-
+            The homeserver does not permit registering the account. This response
+            can be used to identify that a particular ``kind`` of account is not
+            allowed, or that registration is generally not supported by the homeserver.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN",
+                "error": "Registration is disabled"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
@@ -326,13 +348,17 @@ paths:
       description: |-
         Changes the password for an account on this homeserver.
 
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the `User-Interactive Authentication API`_ to
+        ensure the user changing the password is actually the owner of the
+        account.
 
         An access token should be submitted to this endpoint if the client has
         an active session.
 
         The homeserver may change the flows available depending on whether a
-        valid access token is provided.
+        valid access token is provided. The homeserver SHOULD NOT revoke the
+        access token provided in the request, however all other access tokens
+        for the user should be revoked if the request succeeds.
       security:
         - accessToken: []
       operationId: changePassword
@@ -520,13 +546,39 @@ paths:
                 description: |-
                   Additional authentication information for the user-interactive authentication API.
                 "$ref": "definitions/auth_data.yaml"
+              id_server:
+                type: string
+                description: |-
+                  The identity server to unbind all of the user's 3PIDs from.
+                  If not provided, the homeserver MUST use the ``id_server``
+                  that was originally use to bind each identifier. If the
+                  homeserver does not know which ``id_server`` that was,
+                  it must return an ``id_server_unbind_result`` of
+                  ``no-support``.
+                example: "example.org"
       responses:
         200:
           description: The account has been deactivated.
-          examples:
-            application/json: {}
           schema:
             type: object
+            properties:
+              id_server_unbind_result:
+                type: string
+                enum:
+                  - "success"
+                  - "no-support"
+                description: |-
+                  An indicator as to whether or not the homeserver was able to unbind
+                  the user's 3PIDs from the identity server(s). ``success`` indicates
+                  that all identifiers have been unbound from the identity server while
+                  ``no-support`` indicates that one or more identifiers failed to unbind
+                  due to the identity server refusing the request or the homeserver
+                  being unable to determine an identity server to unbind from. This
+                  must be ``success`` if the homeserver has no identifiers to unbind
+                  for the user.
+                example: "success"
+            required:
+              - id_server_unbind_result
         401:
           description: |-
             The homeserver requires additional authentication information.

api/client-server/room_initial_sync.yaml

@@ -43,28 +43,12 @@ paths:
                 "messages": {
                   "chunk": [
                     {
-                      "age": 343513403,
-                      "content": {
-                        "body": "foo",
-                        "msgtype": "m.text"
-                      },
-                      "event_id": "$14328044851tzTJS:example.com",
-                      "origin_server_ts": 1432804485886,
                       "room_id": "!636q39766251:example.com",
-                      "type": "m.room.message",
+                      "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                      "sender": "@alice:example.com"
                     },
                     {
-                      "age": 343511809,
-                      "content": {
-                        "body": "bar",
-                        "msgtype": "m.text"
-                      },
-                      "event_id": "$14328044872spjFg:example.com",
-                      "origin_server_ts": 1432804487480,
                       "room_id": "!636q39766251:example.com",
-                      "type": "m.room.message",
+                      "$ref": "definitions/event-schemas/examples/m.room.message$m.file"
-                      "sender": "@bob:example.com"
                     }
                   ],
                   "end": "s3456_9_0",
@@ -73,81 +57,20 @@ paths:
                 "room_id": "!636q39766251:example.com",
                 "state": [
                   {
-                    "age": 7148266897,
-                    "content": {
-                      "join_rule": "public"
-                    },
-                    "event_id": "$14259997323TLwtb:example.com",
-                    "origin_server_ts": 1425999732392,
                     "room_id": "!636q39766251:example.com",
-                    "state_key": "",
+                    "$ref": "definitions/event-schemas/examples/m.room.join_rules"
-                    "type": "m.room.join_rules",
-                    "sender": "@alice:example.com"
                   },
                   {
-                    "age": 6547561012,
-                    "content": {
-                      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                      "membership": "join"
-                    },
-                    "event_id": "$1426600438280zExKY:example.com",
-                    "membership": "join",
-                    "origin_server_ts": 1426600438277,
                     "room_id": "!636q39766251:example.com",
-                    "state_key": "@alice:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.member"
-                    "type": "m.room.member",
-                    "sender": "@alice:example.com"
                   },
                   {
-                    "age": 7148267200,
-                    "content": {
-                        "creator": "@alice:example.com"
-                    },
-                    "event_id": "$14259997320KhbwJ:example.com",
-                    "origin_server_ts": 1425999732089,
                     "room_id": "!636q39766251:example.com",
-                    "state_key": "",
+                    "$ref": "definitions/event-schemas/examples/m.room.create"
-                    "type": "m.room.create",
-                    "sender": "@alice:example.com"
                   },
                   {
-                    "age": 1622568720,
-                    "content": {
-                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                        "displayname": "Bob",
-                        "membership": "join"
-                    },
-                    "event_id": "$1431525430134MxlLX:example.com",
-                    "origin_server_ts": 1431525430569,
-                    "replaces_state": "$142652023736BSXcM:example.com",
                     "room_id": "!636q39766251:example.com",
-                    "state_key": "@bob:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.power_levels"
-                    "type": "m.room.member",
-                    "sender": "@bob:example.com"
-                  },
-                  {
-                    "age": 7148267004,
-                    "content": {
-                      "ban": 50,
-                      "events": {
-                        "m.room.name": 100,
-                        "m.room.power_levels": 100
-                      },
-                      "events_default": 0,
-                      "kick": 50,
-                      "redact": 50,
-                      "state_default": 50,
-                      "users": {
-                        "@alice:example.com": 100
-                      },
-                      "users_default": 0
-                    },
-                    "event_id": "$14259997322mqfaq:example.com",
-                    "origin_server_ts": 1425999732285,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.power_levels",
-                    "sender": "@alice:example.com"
                   }
                 ],
                 "visibility": "private",

api/client-server/rooms.yaml

@@ -42,7 +42,7 @@ paths:
           name: roomId
           description: The ID of the room the event is in.
           required: true
-          x-example: "!asfDuShaf7Gafaw:matrix.org"
+          x-example: "!636q39766251:matrix.org"
         - in: path
           type: string
           name: eventId
@@ -54,15 +54,9 @@ paths:
           description: The full event.
           examples:
             application/json: {
-                "content": {
+              "room_id": "!636q39766251:matrix.org",
-                  "body": "Hello world!",
+              "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                  "msgtype": "m.text"
+            }
-                },
-                "room_id": "!wfgy43Sg4a:matrix.org",
-                "sender": "@bob:matrix.org",
-                "event_id": "$asfDuShaf7Gafaw:matrix.org",
-                "type": "m.room.message"
-              }
           schema:
             allOf:
               - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
@@ -178,84 +172,23 @@ paths:
           description: The current state of the room
           examples:
             application/json: [
-                {
+              {
-                    "age": 7148266897,
+                "room_id": "!636q39766251:example.com",
-                    "content": {
+                "$ref": "definitions/event-schemas/examples/m.room.join_rules"
-                        "join_rule": "public"
+              },
-                    },
+              {
-                    "event_id": "$14259997323TLwtb:example.com",
+                "room_id": "!636q39766251:example.com",
-                    "origin_server_ts": 1425999732392,
+                "$ref": "definitions/event-schemas/examples/m.room.member"
-                    "room_id": "!636q39766251:example.com",
+              },
-                    "state_key": "",
+              {
-                    "type": "m.room.join_rules",
+                "room_id": "!636q39766251:example.com",
-                    "sender": "@alice:example.com"
+                "$ref": "definitions/event-schemas/examples/m.room.create"
-                },
+              },
-                {
+              {
-                    "age": 6547561012,
+                "room_id": "!636q39766251:example.com",
-                    "content": {
+                "$ref": "definitions/event-schemas/examples/m.room.power_levels"
-                        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
+              }
-                        "membership": "join"
+            ]
-                    },
-                    "event_id": "$1426600438280zExKY:example.com",
-                    "membership": "join",
-                    "origin_server_ts": 1426600438277,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@alice:example.com",
-                    "type": "m.room.member",
-                    "sender": "@alice:example.com"
-                },
-                {
-                    "age": 7148267200,
-                    "content": {
-                        "creator": "@alice:example.com"
-                    },
-                    "event_id": "$14259997320KhbwJ:example.com",
-                    "origin_server_ts": 1425999732089,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.create",
-                    "sender": "@alice:example.com"
-                },
-                {
-                    "age": 1622568720,
-                    "content": {
-                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                        "displayname": "Bob",
-                        "membership": "join"
-                    },
-                    "event_id": "$1431525430134MxlLX:example.com",
-                    "origin_server_ts": 1431525430569,
-                    "replaces_state": "$142652023736BSXcM:example.com",
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@bob:example.com",
-                    "type": "m.room.member",
-                    "sender": "@bob:example.com"
-                },
-                {
-                    "age": 7148267004,
-                    "content": {
-                        "ban": 50,
-                        "events": {
-                            "m.room.name": 100,
-                            "m.room.power_levels": 100
-                         },
-                         "events_default": 0,
-                         "kick": 50,
-                         "redact": 50,
-                         "state_default": 50,
-                         "users": {
-                             "@alice:example.com": 100
-                         },
-                         "users_default": 0
-                    },
-                    "event_id": "$14259997322mqfaq:example.com",
-                    "origin_server_ts": 1425999732285,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.power_levels",
-                    "sender": "@alice:example.com"
-                }
-              ]
           schema:
             type: array
             title: RoomState
@@ -300,33 +233,8 @@ paths:
             application/json: {
                 "chunk": [
                   {
-                    "age": 6547561012,
-                    "content": {
-                      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                      "membership": "join"
-                    },
-                    "event_id": "$1426600438280zExKY:example.com",
-                    "membership": "join",
-                    "origin_server_ts": 1426600438277,
                     "room_id": "!636q39766251:example.com",
-                    "state_key": "@alice:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.member"
-                    "type": "m.room.member",
-                    "sender": "@alice:example.com"
-                  },
-                  {
-                    "age": 1622568720,
-                    "content": {
-                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                        "displayname": "Bob",
-                        "membership": "join"
-                    },
-                    "event_id": "$1431525430134MxlLX:example.com",
-                    "origin_server_ts": 1431525430569,
-                    "replaces_state": "$142652023736BSXcM:example.com",
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@bob:example.com",
-                    "type": "m.room.member",
-                    "sender": "@bob:example.com"
                   }
                 ]
               }

api/client-server/search.yaml

@@ -280,7 +280,7 @@ paths:
                           Any groups that were requested.
 
                           The outer ``string`` key is the group key requested (eg: ``room_id``
-                          or ``sender``). The inner ``string`` key is the grouped value (eg: 
+                          or ``sender``). The inner ``string`` key is the grouped value (eg:
                           a room's ID or a user's ID).
                         additionalProperties:
                           type: object
@@ -347,16 +347,9 @@ paths:
                         {
                           "rank": 0.00424866,
                           "result": {
-                            "age": 526228296,
-                            "content": {
-                              "body": "Test content martians and men",
-                              "msgtype": "m.text"
-                            },
-                            "event_id": "$144429830826TWwbB:localhost",
-                            "origin_server_ts": 1444298308034,
                             "room_id": "!qPewotXpIctQySfjSy:localhost",
-                            "type": "m.room.message",
+                            "event_id": "$144429830826TWwbB:localhost",
-                            "sender": "@test:localhost"
+                            "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
                           }
                         }
                       ]

api/client-server/sync.yaml

@@ -212,30 +212,7 @@ paths:
                             events:
                               description: The StrippedState events that form the invite state.
                               items:
-                                description: |-
+                                $ref: "definitions/event-schemas/schema/stripped_state.yaml"
-                                  A stripped down state event, with only the ``type``, ``state_key``,
-                                  ``sender``, and ``content`` keys.
-                                properties:
-                                  content:
-                                    description: The ``content`` for the event.
-                                    title: EventContent
-                                    type: object
-                                  state_key:
-                                    description: The ``state_key`` for the event.
-                                    type: string
-                                  type:
-                                    description: The ``type`` for the event.
-                                    type: string
-                                  sender:
-                                    description: The ``sender`` for the event.
-                                    type: string
-                                required:
-                                  - type
-                                  - state_key
-                                  - content
-                                  - sender
-                                title: StrippedState
-                                type: object
                               type: array
                   leave:
                     title: Left rooms
@@ -310,11 +287,7 @@ paths:
                 "next_batch": "s72595_4483_1934",
                 "presence": {
                   "events": [
-                    {
+                    {"$ref": "definitions/event-schemas/examples/m.presence"}
-                      "sender": "@alice:example.com",
-                      "type": "m.presence",
-                      "content": {"presence": "online"}
-                    }
                   ]
                 },
                 "account_data": {
@@ -333,36 +306,20 @@ paths:
                       "state": {
                         "events": [
                           {
-                            "sender": "@alice:example.com",
+                            "room_id": "!726s6s6q:example.com",
-                            "type": "m.room.member",
+                            "$ref": "definitions/event-schemas/examples/m.room.member"
-                            "state_key": "@alice:example.com",
-                            "content": {"membership": "join"},
-                            "origin_server_ts": 1417731086795,
-                            "event_id": "$66697273743031:example.com"
                           }
                         ]
                       },
                       "timeline": {
                         "events": [
                           {
-                            "sender": "@bob:example.com",
+                            "room_id": "!726s6s6q:example.com",
-                            "type": "m.room.member",
+                            "$ref": "definitions/event-schemas/examples/m.room.member"
-                            "state_key": "@bob:example.com",
-                            "content": {"membership": "join"},
-                            "prev_content": {"membership": "invite"},
-                            "origin_server_ts": 1417731086795,
-                            "event_id": "$7365636s6r6432:example.com"
                           },
                           {
-                            "sender": "@alice:example.com",
+                            "room_id": "!726s6s6q:example.com",
-                            "type": "m.room.message",
+                            "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
-                            "txn_id": "1234",
-                            "content": {
-                              "body": "I am a fish",
-                              "msgtype": "m.text"
-                            },
-                            "origin_server_ts": 1417731086797,
-                            "event_id": "$74686972643033:example.com"
                           }
                         ],
                         "limited": true,
@@ -370,18 +327,12 @@ paths:
                       },
                       "ephemeral": {
                         "events": [
-                          {
+                          {"$ref": "definitions/event-schemas/examples/m.typing"}
-                            "type": "m.typing",
-                            "content": {"user_ids": ["@alice:example.com"]}
-                          }
                         ]
                       },
                       "account_data": {
                         "events": [
-                          {
+                          {"$ref": "definitions/event-schemas/examples/m.tag"},
-                            "type": "m.tag",
-                            "content": {"tags": {"work": {"order": 1}}}
-                          },
                           {
                             "type": "org.example.custom.room.config",
                             "content": {

api/identity/associations.yaml

@@ -90,7 +90,7 @@ paths:
             }
           schema:
             $ref: "../client-server/definitions/errors/error.yaml"
-  "/bind":
+  "/3pid/bind":
     post:
       summary: Publish an association between a session and a Matrix user ID.
       description: |-
@@ -201,3 +201,86 @@ paths:
             }
           schema:
             $ref: "../client-server/definitions/errors/error.yaml"
+  "/3pid/unbind":
+    post:
+      summary: Remove an association between a session and a Matrix user ID.
+      description: |-
+        Remove an association between a session and a Matrix user ID.
+
+        Future calls to ``/lookup`` for any of the session's 3pids will not
+        return the removed association.
+
+        The identity server should authenticate the request in one of two
+        ways:
+
+        1. The request is signed by the homeserver which controls the ``user_id``.
+        2. The request includes the ``sid`` and ``client_secret`` parameters,
+           as per ``/3pid/bind``, which proves ownership of the 3PID.
+
+        If this endpoint returns a JSON Matrix error, that error should be passed
+        through to the client requesting an unbind through a homeserver, if the
+        homeserver is acting on behalf of a client.
+      operationId: unbind
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+              "sid": "1234",
+              "client_secret": "monkeys_are_GREAT",
+              "mxid": "@ears:example.org",
+              "threepid": {
+                "medium": "email",
+                "address": "monkeys_have_ears@example.org"
+              }
+            }
+            properties:
+              sid:
+                type: string
+                description: The Session ID generated by the ``requestToken`` call.
+              client_secret:
+                type: string
+                description: The client secret passed to the ``requestToken`` call.
+              mxid:
+                type: string
+                description: The Matrix user ID to remove from the 3pids.
+              threepid:
+                type: object
+                title: 3PID
+                description: |-
+                  The 3PID to remove. Must match the 3PID used to generate the session
+                  if using ``sid`` and ``client_secret`` to authenticate this request.
+                properties:
+                  medium:
+                    type: string
+                    description: |-
+                      A medium from the `3PID Types`_ Appendix, matching the medium
+                      of the identifier to unbind.
+                  address:
+                    type: string
+                    description: The 3PID address to remove.
+                required: ['medium', 'address']
+            required: ["threepid", "mxid"]
+      responses:
+        200:
+          description: The association was successfully removed.
+          examples:
+            application/json: {}
+          schema:
+            type: object
+        400:
+          description: |-
+            If the response body is not a JSON Matrix error, the identity server
+            does not support unbinds. If a JSON Matrix error is in the response
+            body, the requesting party should respect the error.
+        404:
+          description: |-
+            If the response body is not a JSON Matrix error, the identity server
+            does not support unbinds. If a JSON Matrix error is in the response
+            body, the requesting party should respect the error.
+        501:
+          description: |-
+            If the response body is not a JSON Matrix error, the identity server
+            does not support unbinds. If a JSON Matrix error is in the response
+            body, the requesting party should respect the error.

api/identity/definitions/request_email_validation.yaml

@@ -39,7 +39,8 @@ properties:
       avoid repeatedly sending the same email in the case of request
       retries between the POSTing user and the identity server.
       The client should increment this value if they desire a new
-      email (e.g. a reminder) to be sent.
+      email (e.g. a reminder) to be sent. If they do not, the server
+      should respond with success but not resend the email.
     example: 1
   next_link:
     type: string

api/identity/store_invite.yaml

@@ -50,31 +50,66 @@ paths:
         requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
 
         Currently, invites may only be issued for 3pids of the ``email`` medium.
+
+        Optional fields in the request should be populated to the best of the
+        server's ability. Identity servers may use these variables when notifying
+        the ``address`` of the pending invite for display purposes.
       operationId: storeInvite
       parameters:
         - in: body
           name: body
           schema:
             type: object
-            example: {
-              "medium": "email",
-              "address": "foo@bar.baz",
-              "room_id": "!something:example.tld",
-              "sender": "@bob:example.com"
-            }
             properties:
               medium:
                 type: string
                 description: The literal string ``email``.
+                example: "email"
               address:
                 type: string
                 description: The email address of the invited user.
+                example: "foo@example.com"
               room_id:
                 type: string
                 description: The Matrix room ID to which the user is invited
+                example: "!something:example.org"
               sender:
                 type: string
                 description: The Matrix user ID of the inviting user
+                example: "@bob:example.com"
+              room_alias:
+                type: string
+                description: |-
+                  The Matrix room alias for the room to which the user is
+                  invited. This should be retrieved from the ``m.room.canonical_alias``
+                  state event.
+                example: "#somewhere:exmaple.org"
+              room_avatar_url:
+                type: string
+                description: |-
+                  The Content URI for the room to which the user is invited. This should
+                  be retrieved from the ``m.room.avatar`` state event.
+                example: "mxc://example.org/s0meM3dia"
+              room_join_rules:
+                type: string
+                description: |-
+                  The ``join_rule`` for the room to which the user is invited. This should
+                  be retrieved from the ``m.room.join_rules`` state event.
+                example: "public"
+              room_name:
+                type: string
+                description: |-
+                  The name of the room to which the user is invited. This should be retrieved
+                  from the ``m.room.name`` state event.
+                example: "Bob's Emporium of Messages"
+              sender_display_name:
+                type: string
+                description: The display name of the user ID initiating the invite.
+                example: "Bob Smith"
+              sender_avatar_url:
+                type: string
+                description: The Content URI for the avatar of the user ID initiating the invite.
+                example: "mxc://example.org/an0th3rM3dia"
             required: ["medium", "address", "room_id", "sender"]
       responses:
         200:

api/server-server/backfill.yaml

@@ -64,7 +64,7 @@ paths:
             A transaction containing the PDUs that preceded the given event(s), including the given
             event(s), up to the given limit.
           schema:
-            $ref: "definitions/transaction.yaml"
+            $ref: "definitions/unlimited_pdu_transaction.yaml"
   "/get_missing_events/{roomId}":
     post:
       summary: Retrieves events that the sender is missing

api/server-server/definitions/pdu_v3.yaml

@@ -20,6 +20,10 @@ allOf:
   - $ref: "unsigned_pdu_base.yaml"
   - type: object
     properties:
+      redacts:
+        type: string
+        description: For redaction events, the ID of the event being redacted.
+        example: "$def/456+oldevent"
       auth_events:
         type: array
         items:

api/server-server/definitions/pdu_v4.yaml

@@ -0,0 +1,47 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# 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.
+type: object
+title: Persistent Data Unit
+description: A persistent data unit (event) for room version 4 and beyond.
+example:
+  $ref: "../examples/pdu_v4.json"
+allOf:
+  - $ref: "pdu_v3.yaml"
+  - type: object
+    properties:
+      redacts:
+        type: string
+        description: For redaction events, the ID of the event being redacted.
+        example: "$def_456-oldevent"
+      auth_events:
+        type: array
+        items:
+          type: string
+          description: Event ID.
+        description: |-
+          Event IDs for the authorization events that would
+          allow this event to be in the room.
+        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
+      prev_events:
+        type: array
+        items:
+          type: string
+          description: Event ID.
+        description: |-
+          Event IDs for the most recent events in the room
+          that the homeserver was aware of when it made this event.
+        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
+    required:
+      - auth_events
+      - prev_events

api/server-server/definitions/single_pdu_transaction.yaml

@@ -0,0 +1,32 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# 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.
+type: object
+allOf:
+  - $ref: "transaction.yaml"
+properties:
+  pdus:
+    type: array
+    description: |-
+      A single PDU. Note that events have a different format depending on the room
+      version - check the `room version specification`_ for precise event formats.
+    items:
+      type: object
+      title: PDU
+      description: |-
+        The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
+        on the room version - check the `room version specification`_ for precise event formats.
+      properties: []
+      example:
+        $ref: "../examples/minimal_pdu.json"
+required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/definitions/unlimited_pdu_transaction.yaml

@@ -0,0 +1,33 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# 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.
+type: object
+allOf:
+  - $ref: "transaction.yaml"
+properties:
+  pdus:
+    type: array
+    description: |-
+      List of persistent updates to rooms. Note that events have a different format
+      depending on the room version - check the `room version specification`_ for
+      precise event formats.
+    items:
+      type: object
+      title: PDU
+      description: |-
+        The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
+        on the room version - check the `room version specification`_ for precise event formats.
+      properties: []
+      example:
+        $ref: "../examples/minimal_pdu.json"
+required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/events.yaml

@@ -156,4 +156,4 @@ paths:
         200:
           description: A transaction containing a single PDU which is the event requested.
           schema:
-            $ref: "definitions/transaction.yaml"
+            $ref: "definitions/single_pdu_transaction.yaml"

api/server-server/examples/pdu_v3.json

@@ -15,5 +15,6 @@
     "prev_events": [
         "$base64encodedeventid",
         "$adifferenteventid"
-    ]
+    ],
+    "redacts": "$some/old+event"
 }

api/server-server/examples/pdu_v4.json

@@ -0,0 +1,12 @@
+{
+    "$ref": "pdu_v3.json",
+    "auth_events": [
+        "$urlsafe_base64_encoded_eventid",
+        "$a-different-event-id"
+    ],
+    "prev_events": [
+        "$urlsafe_base64_encoded_eventid",
+        "$a-different-event-id"
+    ],
+    "redacts": "$some-old_event"
+}

api/server-server/invites-v1.yaml

@@ -82,35 +82,9 @@ paths:
                           identify the room. The recommended events to include are the join rules,
                           canonical alias, avatar, and name of the room.
                         items:
-                          type: object
+                          $ref: "../../event-schemas/schema/stripped_state.yaml"
-                          title: Invite Room State Event
+                        example:
-                          properties:
+                          $ref: "../../event-schemas/examples/invite_room_state.json"
-                            type:
-                              type: string
-                              description: The type of event.
-                              example: "m.room.join_rules"
-                            state_key:
-                              type: string
-                              description: The state key for the event. May be an empty string.
-                              example: ""
-                            content:
-                              type: object
-                              description: The content for the event.
-                            sender:
-                              type: string
-                              description: The sender of the event.
-                              example: "@someone:matrix.org"
-                          required: ['type', 'state_key', 'content', 'sender']
-                        example: [
-                          {
-                            "type": "m.room.join_rules",
-                            "sender": "@someone:matrix.org",
-                            "state_key": "",
-                            "content": {
-                              "join_rule": "public"
-                            }
-                          }
-                        ]
           example: {
             "$ref": "examples/minimal_pdu.json",
             "type": "m.room.member",
@@ -118,26 +92,6 @@ paths:
             "origin": "example.org",
             "origin_server_ts": 1549041175876,
             "sender": "@someone:example.org",
-            "unsigned": {
-              "invite_room_state": [
-                {
-                  "type": "m.room.join_rules",
-                  "sender": "@someone:matrix.org",
-                  "state_key": "",
-                  "content": {
-                    "join_rule": "public"
-                  }
-                },
-                {
-                  "type": "m.room.name",
-                  "sender": "@someone:matrix.org",
-                  "state_key": "",
-                  "content": {
-                    "name": "Cool New Room"
-                  }
-                }
-              ]
-            },
             "content": {
                 "membership": "invite"
             },
@@ -180,24 +134,9 @@ paths:
                   "origin_server_ts": 1549041175876,
                   "sender": "@someone:example.org",
                   "unsigned": {
-                    "invite_room_state": [
+                    "invite_room_state": {
-                      {
+                      "$ref": "../../../event-schemas/examples/invite_room_state.json"
-                        "type": "m.room.join_rules",
+                    }
-                        "sender": "@someone:matrix.org",
-                        "state_key": "",
-                        "content": {
-                          "join_rule": "public"
-                        }
-                      },
-                      {
-                        "type": "m.room.name",
-                        "sender": "@someone:matrix.org",
-                        "state_key": "",
-                        "content": {
-                          "name": "Cool New Room"
-                        }
-                      }
-                    ]
                   },
                   "content": {
                       "membership": "invite"

api/server-server/invites-v2.yaml

@@ -83,35 +83,9 @@ paths:
                   identify the room. The recommended events to include are the join rules,
                   canonical alias, avatar, and name of the room.
                 items:
-                  type: object
+                  $ref: "../../event-schemas/schema/stripped_state.yaml"
-                  title: Invite Room State Event
+                example:
-                  properties:
+                  $ref: "../../event-schemas/examples/invite_room_state.json"
-                    type:
-                      type: string
-                      description: The type of event.
-                      example: "m.room.join_rules"
-                    state_key:
-                      type: string
-                      description: The state key for the event. May be an empty string.
-                      example: ""
-                    content:
-                      type: object
-                      description: The content for the event.
-                    sender:
-                      type: string
-                      description: The sender of the event.
-                      example: "@someone:matrix.org"
-                  required: ['type', 'state_key', 'content', 'sender']
-                example: [
-                  {
-                    "type": "m.room.join_rules",
-                    "sender": "@someone:matrix.org",
-                    "state_key": "",
-                    "content": {
-                      "join_rule": "public"
-                    }
-                  }
-                ]
             required: ['room_version', 'event']
           example: {
             "room_version": "2",
@@ -130,25 +104,7 @@ paths:
                   "ed25519:key_version": "SomeSignatureHere"
                 },
               }
-            },
+            }
-            "invite_room_state": [
-              {
-                "type": "m.room.join_rules",
-                "sender": "@someone:matrix.org",
-                "state_key": "",
-                "content": {
-                  "join_rule": "public"
-                }
-              },
-              {
-                "type": "m.room.name",
-                "sender": "@someone:matrix.org",
-                "state_key": "",
-                "content": {
-                  "name": "Cool New Room"
-                }
-              }
-            ]
           }
       responses:
         200:
@@ -174,24 +130,9 @@ paths:
                 "origin_server_ts": 1549041175876,
                 "sender": "@someone:example.org",
                 "unsigned": {
-                  "invite_room_state": [
+                  "invite_room_state": {
-                    {
+                    "$ref": "../../../event-schemas/examples/invite_room_state.json"
-                      "type": "m.room.join_rules",
+                  }
-                      "sender": "@someone:matrix.org",
-                      "state_key": "",
-                      "content": {
-                        "join_rule": "public"
-                      }
-                    },
-                    {
-                      "type": "m.room.name",
-                      "sender": "@someone:matrix.org",
-                      "state_key": "",
-                      "content": {
-                        "name": "Cool New Room"
-                      }
-                    }
-                  ]
                 },
                 "content": {
                     "membership": "invite"

api/server-server/user_keys.yaml

@@ -63,7 +63,7 @@ paths:
               - one_time_keys
       responses:
         200:
-          description: The claimed keys
+          description: The claimed keys.
           schema:
             type: object
             properties:

changelogs/application_service/newsfragments/1650.clarification

@@ -0,0 +1 @@
+Change examples to use example.org instead of a real domain.

changelogs/application_service/newsfragments/2037.clarification

@@ -0,0 +1 @@
+Add missing definition for how appservices verify requests came from a homeserver.

changelogs/client_server/newsfragments/1650.clarification

@@ -0,0 +1 @@
+Change examples to use example.org instead of a real domain.

changelogs/client_server/newsfragments/1656.clarification

@@ -0,0 +1 @@
+Clarify that ``state_default`` in ``m.room.power_levels`` always defaults to 50.

changelogs/client_server/newsfragments/1701.feature

@@ -1 +1 @@
-Documented megolm session export format.
+Add megolm session export format.

changelogs/client_server/newsfragments/1744.clarification

@@ -1 +1 @@
-Add missing status_msg to m.presence schema.
+Add missing ``status_msg`` to ``m.presence`` schema.

changelogs/client_server/newsfragments/1889.clarification

@@ -1 +1 @@
-Add the missing `m.push_rules` event schema.
+Add the missing ``m.push_rules`` event schema.

changelogs/client_server/newsfragments/1891.clarification

@@ -0,0 +1 @@
+Clarify how modern day local echo is meant to be solved by clients.

changelogs/client_server/newsfragments/1969.clarification

@@ -0,0 +1 @@
+Fix various spelling mistakes throughout the specification.

changelogs/client_server/newsfragments/1975.clarification

@@ -0,0 +1 @@
+Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``.

changelogs/client_server/newsfragments/1988.clarification

@@ -0,0 +1 @@
+Fix various spelling mistakes throughout the specification.

changelogs/client_server/newsfragments/1989.clarification

@@ -0,0 +1 @@
+Fix various spelling mistakes throughout the specification.

changelogs/client_server/newsfragments/1991.clarification

@@ -0,0 +1 @@
+Fix various spelling mistakes throughout the specification.

changelogs/client_server/newsfragments/1992.clarification

@@ -0,0 +1 @@
+Fix various spelling mistakes throughout the specification.

changelogs/client_server/newsfragments/1999.clarification

@@ -0,0 +1 @@
+Clarify how ``m.login.dummy`` can be used to disambiguate login flows.

changelogs/client_server/newsfragments/2016.clarification

@@ -0,0 +1 @@
+Remove ``prev_content`` from the redaction algorithm's essential keys list.

changelogs/client_server/newsfragments/2020.feature

@@ -0,0 +1 @@
+Add a ``.m.rule.tombstone`` default push rule for room ugprade notifications.

changelogs/client_server/newsfragments/2025.clarification

@@ -0,0 +1 @@
+Fix the ``third_party_signed`` definitions for the join APIs.

changelogs/client_server/newsfragments/2026.feature

@@ -0,0 +1 @@
+Add support for sending server notices to clients.

changelogs/client_server/newsfragments/2027.clarification

@@ -0,0 +1 @@
+Clarify why User Interactive Auth is used on password changes and how access tokens are handled.

changelogs/client_server/newsfragments/2028.clarification

@@ -0,0 +1 @@
+Clarify that devices are deleted upon logout.

changelogs/client_server/newsfragments/2029.clarification

@@ -0,0 +1 @@
+Add ``M_NOT_FOUND`` error definition for deleting room aliases.

changelogs/client_server/newsfragments/2030.feature

@@ -0,0 +1 @@
+Add MSISDN (phone number) support to User-Interactive Authentication.

changelogs/client_server/newsfragments/2031.clarification

@@ -0,0 +1 @@
+Add missing ``reason`` to ``m.call.hangup``.

changelogs/client_server/newsfragments/2032.clarification

@@ -0,0 +1 @@
+Clarify how redactions affect room state.

changelogs/client_server/newsfragments/2036.clarification

@@ -0,0 +1 @@
+Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers.

changelogs/client_server/newsfragments/2041.clarification

@@ -0,0 +1 @@
+Fix example ``Content-Type`` for ``/media/upload`` request.

changelogs/client_server/newsfragments/2042.clarification

@@ -0,0 +1 @@
+Clarify that login flows are meant to be completed in order.

changelogs/client_server/newsfragments/2043.clarification

@@ -0,0 +1 @@
+Clarify that clients should not send read receipts for their own messages.

changelogs/client_server/newsfragments/2046.feature

@@ -0,0 +1 @@
+Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server.

changelogs/client_server/newsfragments/2051.clarification

@@ -0,0 +1 @@
+Use consistent examples of events throughout the specification.

changelogs/client_server/newsfragments/2052.clarification

@@ -0,0 +1 @@
+Clarify which push rule condition kinds exist.

changelogs/client_server/newsfragments/2053.clarification

@@ -0,0 +1 @@
+Clarify the required fields on ``m.file`` (and similar) messages.

changelogs/client_server/newsfragments/2054.clarification

@@ -0,0 +1 @@
+Clarify that User-Interactive Authentication stages cannot be attempted more than once.

changelogs/client_server/newsfragments/2055.clarification

@@ -0,0 +1 @@
+Clarify which parameters apply in what scenarios on ``/register``.

changelogs/client_server/newsfragments/2056.clarification

@@ -0,0 +1 @@
+Clarify how to interpret changes of ``membership`` over time.

changelogs/client_server/newsfragments/2059.feature

@@ -0,0 +1 @@
+Add support for Olm sessions becoming un-stuck.

changelogs/client_server/newsfragments/2067.clarification

@@ -0,0 +1 @@
+Clarify exactly what invite_room_state consists of.

changelogs/client_server/newsfragments/2069.clarification

@@ -0,0 +1 @@
+Clarify the order events in chunk are returned in for ``/messages``.

changelogs/client_server/newsfragments/2072.feature

@@ -0,0 +1 @@
+Add interactive device verification, including a common framework for device verification.

changelogs/client_server/newsfragments/2090.clarification

@@ -0,0 +1 @@
+Clarify when authorization and rate-limiting are not applicable.

changelogs/identity_service/newsfragments/1967.clarification

@@ -0,0 +1 @@
+Fix route for ``/3pid/bind``.

changelogs/identity_service/newsfragments/2046.new

@@ -0,0 +1 @@
+Add ``/3pid/unbind`` for removing 3PIDs.

changelogs/identity_service/newsfragments/2049.clarification

@@ -0,0 +1 @@
+Add missing aesthetic parameters to ``/store-invite``.

changelogs/identity_service/newsfragments/2057.clarification

@@ -0,0 +1 @@
+Clarify what the client should receive upon sending an identical email validation request multiple times.

changelogs/identity_service/newsfragments/2086.clarification

@@ -0,0 +1 @@
+Clarify that the default transport is JSON over HTTP.

changelogs/server_server/newsfragments/1650.clarification

@@ -0,0 +1 @@
+Change examples to use example.org instead of a real domain.

changelogs/server_server/newsfragments/1904.clarification

@@ -1 +0,0 @@
-Fix the `access_token` parameter in the open_id endpoint.

changelogs/server_server/newsfragments/1906.clarification

@@ -0,0 +1 @@
+Fix the ``access_token`` parameter in the open_id endpoint.

changelogs/server_server/newsfragments/1991.clarification

@@ -0,0 +1 @@
+Fix various spelling mistakes throughout the specification.

changelogs/server_server/newsfragments/2067.clarification

@@ -0,0 +1 @@
+Clarify exactly what invite_room_state consists of.

changelogs/server_server/newsfragments/2081.clarification

@@ -0,0 +1 @@
+Clarify which servers are supposed to sign events.

changelogs/server_server/newsfragments/2095.clarification

@@ -0,0 +1 @@
+Clarify how many PDUs are contained in transaction objects for various endpoints.

data-definitions/sas-emoji.json

@@ -0,0 +1,66 @@
+[
+    {"number": 0, "emoji": "🐶", "description": "Dog", "unicode": "U+1F436"},
+    {"number": 1, "emoji": "🐱", "description": "Cat", "unicode": "U+1F431"},
+    {"number": 2, "emoji": "🦁", "description": "Lion", "unicode": "U+1F981"},
+    {"number": 3, "emoji": "🐎", "description": "Horse", "unicode": "U+1F40E"},
+    {"number": 4, "emoji": "🦄", "description": "Unicorn", "unicode": "U+1F984"},
+    {"number": 5, "emoji": "🐷", "description": "Pig", "unicode": "U+1F437"},
+    {"number": 6, "emoji": "🐘", "description": "Elephant", "unicode": "U+1F418"},
+    {"number": 7, "emoji": "🐰", "description": "Rabbit", "unicode": "U+1F430"},
+    {"number": 8, "emoji": "🐼", "description": "Panda", "unicode": "U+1F43C"},
+    {"number": 9, "emoji": "🐓", "description": "Rooster", "unicode": "U+1F413"},
+    {"number": 10, "emoji": "🐧", "description": "Penguin", "unicode": "U+1F427"},
+    {"number": 11, "emoji": "🐢", "description": "Turtle", "unicode": "U+1F422"},
+    {"number": 12, "emoji": "🐟", "description": "Fish", "unicode": "U+1F41F"},
+    {"number": 13, "emoji": "🐙", "description": "Octopus", "unicode": "U+1F419"},
+    {"number": 14, "emoji": "🦋", "description": "Butterfly", "unicode": "U+1F98B"},
+    {"number": 15, "emoji": "🌷", "description": "Flower", "unicode": "U+1F337"},
+    {"number": 16, "emoji": "🌳", "description": "Tree", "unicode": "U+1F333"},
+    {"number": 17, "emoji": "🌵", "description": "Cactus", "unicode": "U+1F335"},
+    {"number": 18, "emoji": "🍄", "description": "Mushroom", "unicode": "U+1F344"},
+    {"number": 19, "emoji": "🌏", "description": "Globe", "unicode": "U+1F30F"},
+    {"number": 20, "emoji": "🌙", "description": "Moon", "unicode": "U+1F319"},
+    {"number": 21, "emoji": "☁️", "description": "Cloud", "unicode": "U+2601U+FE0F"},
+    {"number": 22, "emoji": "🔥", "description": "Fire", "unicode": "U+1F525"},
+    {"number": 23, "emoji": "🍌", "description": "Banana", "unicode": "U+1F34C"},
+    {"number": 24, "emoji": "🍎", "description": "Apple", "unicode": "U+1F34E"},
+    {"number": 25, "emoji": "🍓", "description": "Strawberry", "unicode": "U+1F353"},
+    {"number": 26, "emoji": "🌽", "description": "Corn", "unicode": "U+1F33D"},
+    {"number": 27, "emoji": "🍕", "description": "Pizza", "unicode": "U+1F355"},
+    {"number": 28, "emoji": "🎂", "description": "Cake", "unicode": "U+1F382"},
+    {"number": 29, "emoji": "❤️", "description": "Heart", "unicode": "U+2764U+FE0F"},
+    {"number": 30, "emoji": "😀", "description": "Smiley", "unicode": "U+1F600"},
+    {"number": 31, "emoji": "🤖", "description": "Robot", "unicode": "U+1F916"},
+    {"number": 32, "emoji": "🎩", "description": "Hat", "unicode": "U+1F3A9"},
+    {"number": 33, "emoji": "👓", "description": "Glasses", "unicode": "U+1F453"},
+    {"number": 34, "emoji": "🔧", "description": "Spanner", "unicode": "U+1F527"},
+    {"number": 35, "emoji": "🎅", "description": "Santa", "unicode": "U+1F385"},
+    {"number": 36, "emoji": "👍", "description": "Thumbs Up", "unicode": "U+1F44D"},
+    {"number": 37, "emoji": "☂️", "description": "Umbrella", "unicode": "U+2602U+FE0F"},
+    {"number": 38, "emoji": "⌛", "description": "Hourglass", "unicode": "U+231B"},
+    {"number": 39, "emoji": "⏰", "description": "Clock", "unicode": "U+23F0"},
+    {"number": 40, "emoji": "🎁", "description": "Gift", "unicode": "U+1F381"},
+    {"number": 41, "emoji": "💡", "description": "Light Bulb", "unicode": "U+1F4A1"},
+    {"number": 42, "emoji": "📕", "description": "Book", "unicode": "U+1F4D5"},
+    {"number": 43, "emoji": "✏️", "description": "Pencil", "unicode": "U+270FU+FE0F"},
+    {"number": 44, "emoji": "📎", "description": "Paperclip", "unicode": "U+1F4CE"},
+    {"number": 45, "emoji": "✂️", "description": "Scissors", "unicode": "U+2702U+FE0F"},
+    {"number": 46, "emoji": "🔒", "description": "Lock", "unicode": "U+1F512"},
+    {"number": 47, "emoji": "🔑", "description": "Key", "unicode": "U+1F511"},
+    {"number": 48, "emoji": "🔨", "description": "Hammer", "unicode": "U+1F528"},
+    {"number": 49, "emoji": "☎️", "description": "Telephone", "unicode": "U+260EU+FE0F"},
+    {"number": 50, "emoji": "🏁", "description": "Flag", "unicode": "U+1F3C1"},
+    {"number": 51, "emoji": "🚂", "description": "Train", "unicode": "U+1F682"},
+    {"number": 52, "emoji": "🚲", "description": "Bicycle", "unicode": "U+1F6B2"},
+    {"number": 53, "emoji": "✈️", "description": "Aeroplane", "unicode": "U+2708U+FE0F"},
+    {"number": 54, "emoji": "🚀", "description": "Rocket", "unicode": "U+1F680"},
+    {"number": 55, "emoji": "🏆", "description": "Trophy", "unicode": "U+1F3C6"},
+    {"number": 56, "emoji": "⚽", "description": "Ball", "unicode": "U+26BD"},
+    {"number": 57, "emoji": "🎸", "description": "Guitar", "unicode": "U+1F3B8"},
+    {"number": 58, "emoji": "🎺", "description": "Trumpet", "unicode": "U+1F3BA"},
+    {"number": 59, "emoji": "🔔", "description": "Bell", "unicode": "U+1F514"},
+    {"number": 60, "emoji": "⚓", "description": "Anchor", "unicode": "U+2693"},
+    {"number": 61, "emoji": "🎧", "description": "Headphones", "unicode": "U+1F3A7"},
+    {"number": 62, "emoji": "📁", "description": "Folder", "unicode": "U+1F4C1"},
+    {"number": 63, "emoji": "📌", "description": "Pin", "unicode": "U+1F4CC"}
+]

event-schemas/check_examples.py

@@ -106,14 +106,17 @@ def check_example_dir(exampledir, schemadir):
             if filename.startswith("."):
                 # Skip over any vim .swp files.
                 continue
+            if filename.endswith(".json"):
+                # Skip over any explicit examples (partial event definitions)
+                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:
+            if schemapath.find("$") >= 0:
-                schemapath = schemapath[:schemapath.find("#")]
+                schemapath = schemapath[:schemapath.find("$")]
             try:
                 check_example_file(examplepath, schemapath)
             except Exception as e:

event-schemas/examples/invite_room_state.json

@@ -0,0 +1,18 @@
+[
+    {
+        "type": "m.room.name",
+        "sender": "@bob:example.org",
+        "state_key": "",
+        "content": {
+            "name": "Example Room"
+        }
+    },
+    {
+        "type": "m.room.join_rules",
+        "sender": "@bob:example.org",
+        "state_key": "",
+        "content": {
+            "join_rule": "invite"
+        }
+    }
+]

event-schemas/examples/m.dummy

@@ -0,0 +1,4 @@
+{
+  "content": {},
+  "type": "m.dummy"
+}

event-schemas/examples/m.key.verification.accept

@@ -0,0 +1,12 @@
+{
+    "type": "m.key.verification.accept",
+    "content": {
+        "transaction_id": "S0meUniqueAndOpaqueString",
+        "method": "m.sas.v1",
+        "key_agreement_protocol": "curve25519",
+        "hash": "sha256",
+        "message_authentication_code": "hkdf-hmac-sha256",
+        "short_authentication_string": ["decimal", "emoji"],
+        "commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+    }
+}

event-schemas/examples/m.key.verification.cancel

@@ -0,0 +1,8 @@
+{
+    "type": "m.key.verification.cancel",
+    "content": {
+        "transaction_id": "S0meUniqueAndOpaqueString",
+        "code": "m.user",
+        "reason": "User rejected the key verification request"
+    }
+}

event-schemas/examples/m.key.verification.key

@@ -0,0 +1,7 @@
+{
+    "type": "m.key.verification.key",
+    "content": {
+        "transaction_id": "S0meUniqueAndOpaqueString",
+        "key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+    }
+}

event-schemas/examples/m.key.verification.mac

@@ -0,0 +1,10 @@
+{
+    "type": "m.key.verification.mac",
+    "content": {
+        "transaction_id": "S0meUniqueAndOpaqueString",
+        "keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA",
+        "mac": {
+            "ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+        }
+    }
+}

event-schemas/examples/m.key.verification.request

@@ -0,0 +1,11 @@
+{
+    "type": "m.key.verification.request",
+    "content": {
+        "from_device": "AliceDevice2",
+        "transaction_id": "S0meUniqueAndOpaqueString",
+        "methods": [
+            "m.sas.v1"
+        ],
+        "timestamp": 1559598944869
+    }
+}

event-schemas/examples/m.key.verification.start

@@ -0,0 +1,8 @@
+{
+    "type": "m.key.verification.start",
+    "content": {
+        "from_device": "BobDevice1",
+        "transaction_id": "S0meUniqueAndOpaqueString",
+        "method": "m.sas.v1"
+    }
+}

event-schemas/examples/m.key.verification.start$m.sas.v1

@@ -0,0 +1,12 @@
+{
+    "type": "m.key.verification.start",
+    "content": {
+        "from_device": "BobDevice1",
+        "transaction_id": "S0meUniqueAndOpaqueString",
+        "method": "m.sas.v1",
+        "key_agreement_protocols": ["curve25519"],
+        "hashes": ["sha256"],
+        "message_authentication_codes": ["hkdf-hmac-sha256"],
+        "short_authentication_string": ["decimal", "emoji"]
+    }
+}