Merge branch 'main' into update-openapi

2026-03-26 21:14:09 +01:00 · 2023-06-07 12:13:48 +02:00 · 2023-06-07 12:13:48 +02:00 · e72212bb97
parent e2efbfbe5c c64a616d54
commit e72212bb97
93 changed files with 1539 additions and 209 deletions
--- a/.github/ISSUE_TEMPLATE/release.md
+++ b/.github/ISSUE_TEMPLATE/release.md
@ -0,0 +1,34 @@
+---
+name: [SCT] Release checklist
+about: Used by the Spec Core Team to create a new release.
+title: 'Matrix 1.X'
+labels: 'release-blocker'
+assignees: ''
+
+---
+
+<!-- ------------------------------------------------------------------------ -->
+<!-- Please asssign the release coordinator (probably yourself) to this issue -->
+<!-- ------------------------------------------------------------------------ -->
+
+Date: **Thursday, May 25, 2023** <!-- CHANGE ME -->
+Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
+
+Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
+
+* [ ] Blog post written
+* [ ] Check for release blockers that may have been missed
+* [ ] Review/fix the changelog
+
+Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
+* [ ] Branch stuffs
+* [ ] Github release artifact
+* [ ] Published to spec.matrix.org
+* [ ] All links work
+* [ ] Publish blog post
+* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted
+* [ ] Post to Twitter/Mastodon
+* [ ] Close this issue
+
+Known release blockers:
+* [ ] <!-- Issue/PR link -->
--- a/changelogs/appendices/newsfragments/1468.clarification
+++ b/changelogs/appendices/newsfragments/1468.clarification
@ -1 +0,0 @@
-Clarify that the term "Canonical JSON" is a specific thing within the matrix specification.
--- a/changelogs/appendices/newsfragments/1483.clarification
+++ b/changelogs/appendices/newsfragments/1483.clarification
@ -1 +0,0 @@
-Remove references to groups
--- a/changelogs/appendices/newsfragments/1484.clarification
+++ b/changelogs/appendices/newsfragments/1484.clarification
@ -1 +0,0 @@
-Clarifications of event ID formats in early room versions
--- a/changelogs/application_service/newsfragments/1447.clarification
+++ b/changelogs/application_service/newsfragments/1447.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1424.clarification
+++ b/changelogs/client_server/newsfragments/1424.clarification
@ -1 +0,0 @@
-Clarify the sections of the specification concerning aggregation of child events.
--- a/changelogs/client_server/newsfragments/1432.clarification
+++ b/changelogs/client_server/newsfragments/1432.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1439.clarification
+++ b/changelogs/client_server/newsfragments/1439.clarification
@ -1 +0,0 @@
-Clarify that reply chain fallback for threads may not be present.
--- a/changelogs/client_server/newsfragments/1440.feature
+++ b/changelogs/client_server/newsfragments/1440.feature
@ -1 +0,0 @@
-Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925).
--- a/changelogs/client_server/newsfragments/1441.clarification
+++ b/changelogs/client_server/newsfragments/1441.clarification
@ -1 +0,0 @@
-Clarify what event property the content-specific push rules match against.
--- a/changelogs/client_server/newsfragments/1442.clarification
+++ b/changelogs/client_server/newsfragments/1442.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1447.clarification
+++ b/changelogs/client_server/newsfragments/1447.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1449.clarification
+++ b/changelogs/client_server/newsfragments/1449.clarification
@ -1 +0,0 @@
-Clarify the semantics that make requests idempotent.
--- a/changelogs/client_server/newsfragments/1455.clarification
+++ b/changelogs/client_server/newsfragments/1455.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1457.clarification
+++ b/changelogs/client_server/newsfragments/1457.clarification
@ -1 +0,0 @@
-Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
--- a/changelogs/client_server/newsfragments/1461.clarification
+++ b/changelogs/client_server/newsfragments/1461.clarification
@ -1 +0,0 @@
-Improve documentation of how clients use push rules.
--- a/changelogs/client_server/newsfragments/1463.clarification
+++ b/changelogs/client_server/newsfragments/1463.clarification
@ -1 +0,0 @@
-Clarify that servers should enforce a default `limit` on a filter if one is not specified.
--- a/changelogs/client_server/newsfragments/1464.clarification
+++ b/changelogs/client_server/newsfragments/1464.clarification
@ -1 +0,0 @@
-Disambiguate using property names with dots in them during push rule processing, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980).
--- a/changelogs/client_server/newsfragments/1464.feature
+++ b/changelogs/client_server/newsfragments/1464.feature
@ -1 +0,0 @@
-Add new push rule conditions: `event_property_is` and `event_property_contains` from [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966).
--- a/changelogs/client_server/newsfragments/1465.clarifications
+++ b/changelogs/client_server/newsfragments/1465.clarifications
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1474.clarification
+++ b/changelogs/client_server/newsfragments/1474.clarification
@ -1 +0,0 @@
-Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks.
--- a/changelogs/client_server/newsfragments/1475.feature
+++ b/changelogs/client_server/newsfragments/1475.feature
@ -1 +0,0 @@
-Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677).
--- a/changelogs/client_server/newsfragments/1479.clarification
+++ b/changelogs/client_server/newsfragments/1479.clarification
@ -1 +0,0 @@
-Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room.
--- a/changelogs/client_server/newsfragments/1485.clarification
+++ b/changelogs/client_server/newsfragments/1485.clarification
@ -1 +0,0 @@
-Remove fictitious `token` parameter on `/keys/query` endpoint
--- a/changelogs/client_server/newsfragments/1487.clarification
+++ b/changelogs/client_server/newsfragments/1487.clarification
@ -1 +0,0 @@
-Fix rendering of properties with a list of types
--- a/changelogs/client_server/newsfragments/1495.clarification
+++ b/changelogs/client_server/newsfragments/1495.clarification
@ -1 +0,0 @@
-Clarify parts of the end-to-end encryption sections.
--- a/changelogs/client_server/newsfragments/1499.feature
+++ b/changelogs/client_server/newsfragments/1499.feature
@ -1,2 +0,0 @@
-Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246).
-
--- a/changelogs/client_server/newsfragments/1500.clarification
+++ b/changelogs/client_server/newsfragments/1500.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1501.clarification
+++ b/changelogs/client_server/newsfragments/1501.clarification
@ -1 +0,0 @@
-Remove the `dont_notify` and `coalesce` push rule actions per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987).
--- a/changelogs/client_server/newsfragments/1507.clarification
+++ b/changelogs/client_server/newsfragments/1507.clarification
@ -1 +0,0 @@
-Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks.
--- a/changelogs/client_server/newsfragments/1509.clarification
+++ b/changelogs/client_server/newsfragments/1509.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/1510.feature
+++ b/changelogs/client_server/newsfragments/1510.feature
@ -1,2 +0,0 @@
-Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246).
-
--- a/changelogs/identity_service/newsfragments/1457.clarification
+++ b/changelogs/identity_service/newsfragments/1457.clarification
@ -1 +0,0 @@
-Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
--- a/changelogs/identity_service/newsfragments/1486.clarification
+++ b/changelogs/identity_service/newsfragments/1486.clarification
@ -1 +0,0 @@
-Corrections to the response format of `/_matrix/identity/v2/store-invite`.
--- a/changelogs/internal/newsfragments/1444.clarification
+++ b/changelogs/internal/newsfragments/1444.clarification
@ -1 +0,0 @@
-Update references to Inter font.
--- a/changelogs/internal/newsfragments/1446.clarification
+++ b/changelogs/internal/newsfragments/1446.clarification
@ -1 +0,0 @@
-Endpoint disclosures now hide everything but the URL.
--- a/changelogs/internal/newsfragments/1476.clarification
+++ b/changelogs/internal/newsfragments/1476.clarification
@ -1 +0,0 @@
-Minor cleanups to the GitHub Actions workflows
--- a/changelogs/internal/newsfragments/1488.clarification
+++ b/changelogs/internal/newsfragments/1488.clarification
@ -1 +0,0 @@
-Fix generation of anchors for additional properties
--- a/changelogs/internal/newsfragments/1542.clarification
+++ b/changelogs/internal/newsfragments/1542.clarification
@ -0,0 +1 @@
+Update the CI to validate the file extension of changelog entries.
--- a/changelogs/internal/newsfragments/1549.clarification
+++ b/changelogs/internal/newsfragments/1549.clarification
@ -0,0 +1 @@
+Disclosure sections now only display their title when collapsed.
--- a/changelogs/room_versions/newsfragments/1484.clarification
+++ b/changelogs/room_versions/newsfragments/1484.clarification
@ -1 +0,0 @@
-Clarifications of event ID formats in early room versions
--- a/changelogs/server_server/newsfragments/1431.clarification
+++ b/changelogs/server_server/newsfragments/1431.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/server_server/newsfragments/1447.clarification
+++ b/changelogs/server_server/newsfragments/1447.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/server_server/newsfragments/1454.clarification
+++ b/changelogs/server_server/newsfragments/1454.clarification
@ -1 +0,0 @@
-Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`.
--- a/changelogs/server_server/newsfragments/1457.clarification
+++ b/changelogs/server_server/newsfragments/1457.clarification
@ -1 +0,0 @@
-Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
--- a/changelogs/server_server/newsfragments/1466.clarification
+++ b/changelogs/server_server/newsfragments/1466.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/server_server/newsfragments/1473.clarification
+++ b/changelogs/server_server/newsfragments/1473.clarification
@ -1 +0,0 @@
-* Remove leftover `{key_id}` from `/_matrix/key/v2/server/`
--- a/changelogs/server_server/newsfragments/1521.clarification
+++ b/changelogs/server_server/newsfragments/1521.clarification
@ -0,0 +1 @@
+Document why `/state_ids` can respond with a 404.
--- a/config.toml
+++ b/config.toml
@ -53,8 +53,8 @@ current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
 # major = "1"
-# minor = "6"
-# release_date = "February 14, 2023"
+# minor = "7"
+# release_date = "May 25, 2023"

 # User interface configuration
 [params.ui]
--- a/content/_index.md
+++ b/content/_index.md
@ -357,8 +357,8 @@ servers that are in the room that can be used to join via.

    HTTP GET
    #matrix:example.org      !aaabaa:matrix.org
-       |                    ^
-       |                    |
+           |                    ^
+           |                    |
    _______V____________________|____
    |          example.org           |
    | Mappings:                      |
--- a/content/application-service-api.md
+++ b/content/application-service-api.md
@ -207,6 +207,54 @@ processed the events.

 {{% http-api spec="application-service" api="transactions" %}}

+#### Pinging
+
+{{% added-in v="1.7" %}}
+
+The application service API includes a ping mechanism to allow
+appservices to ensure that the homeserver can reach the appservice.
+Appservices may use this mechanism to detect misconfigurations and
+report them appropriately.
+
+Implementations using this mechanism should take care to not fail
+entirely in the event of temporary issues, e.g. gracefully handling
+cases where the appservice is started before the homeserver.
+
+The mechanism works as follows (note: the human-readable `error` fields
+have been omitted for brevity):
+
+**Typical**
+
+```
+AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
+    HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
+    HS <--- AS : 200 OK {}
+AS <--- HS : 200 OK {"duration_ms": 123}
+```
+
+**Incorrect `hs_token`**
+
+```
+AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
+    HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
+    HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"}
+AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body": "{\"errcode\": \"M_FORBIDDEN\"}"}
+```
+
+**Can't connect to appservice**
+
+```
+AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
+    HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
+AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"}
+```
+
+The `/_matrix/app/v1/ping` endpoint is described here. The
+[`/_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping)
+endpoint is under the Client-Server API extensions section below.
+
+{{% http-api spec="application-service" api="ping" %}}
+
 #### Querying

 The application service API includes two querying APIs: for room aliases
@ -388,6 +436,15 @@ an application service-defined namespace will receive the same
 `M_EXCLUSIVE` error code, but only if the application service has
 defined the namespace as `exclusive`.

+#### Pinging
+
+{{% added-in v="1.7" %}}
+
+This is the client-server API companion endpoint for the
+[pinging](#pinging) mechanism described above.
+
+{{% http-api spec="client-server" api="appservice_ping" %}}
+
 #### Using `/sync` and `/events`

 Application services wishing to use `/sync` or `/events` from the
--- a/content/changelog/v1.7.md
+++ b/content/changelog/v1.7.md
@ -0,0 +1,147 @@
+---
+date: 2023-05-25T09:47:21-06:00
+---
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    v1.7  = Replaced by the version number (eg: v1.2)
+    May 25, 2023     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## v1.7
+
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.7">https://github.com/matrix-org/matrix-spec/tree/v1.7</a></td>
+<tr><th>Release date</th><td>May 25, 2023</td>
+</table>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
+### Client-Server API
+
+
+<strong>New Endpoints</strong>
+
+
+- [`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499))
+- [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499))
+- [`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530))
+
+
+<strong>Backwards Compatible Changes</strong>
+
+
+- Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). ([#1440](https://github.com/matrix-org/matrix-spec/issues/1440), [#1525](https://github.com/matrix-org/matrix-spec/issues/1525))
+- Add new push rule conditions `event_property_is` and `event_property_contains`, as per [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464))
+- Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). ([#1475](https://github.com/matrix-org/matrix-spec/issues/1475), [#1531](https://github.com/matrix-org/matrix-spec/issues/1531))
+- Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499), [#1510](https://github.com/matrix-org/matrix-spec/issues/1510))
+- Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other notification behaviour, as per [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). ([#1508](https://github.com/matrix-org/matrix-spec/issues/1508))
+- Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). ([#1511](https://github.com/matrix-org/matrix-spec/issues/1511), [#1540](https://github.com/matrix-org/matrix-spec/issues/1540))
+- Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). ([#1526](https://github.com/matrix-org/matrix-spec/issues/1526))
+- Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). ([#1529](https://github.com/matrix-org/matrix-spec/issues/1529))
+- Add an ability to use an existing session to log in another, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530))
+
+
+<strong>Spec Clarifications</strong>
+
+
+- Clarify the sections of the specification concerning aggregation of child events. ([#1424](https://github.com/matrix-org/matrix-spec/issues/1424))
+- Fix various typos throughout the specification. ([#1432](https://github.com/matrix-org/matrix-spec/issues/1432), [#1442](https://github.com/matrix-org/matrix-spec/issues/1442), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1455](https://github.com/matrix-org/matrix-spec/issues/1455), [#1465](https://github.com/matrix-org/matrix-spec/issues/1465), [#1500](https://github.com/matrix-org/matrix-spec/issues/1500), [#1509](https://github.com/matrix-org/matrix-spec/issues/1509))
+- Clarify that reply chain fallback for threads might not be present. ([#1439](https://github.com/matrix-org/matrix-spec/issues/1439))
+- Clarify what event property the content-specific push rules match against. ([#1441](https://github.com/matrix-org/matrix-spec/issues/1441))
+- Clarify the semantics that make requests idempotent. ([#1449](https://github.com/matrix-org/matrix-spec/issues/1449))
+- Improve documentation of how clients use push rules. ([#1461](https://github.com/matrix-org/matrix-spec/issues/1461))
+- Clarify that servers should enforce a default `limit` on a filter if one is not specified. ([#1463](https://github.com/matrix-org/matrix-spec/issues/1463))
+- Disambiguate using property names with dots in them during push rule processing, as per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464))
+- Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. ([#1474](https://github.com/matrix-org/matrix-spec/issues/1474))
+- Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room. ([#1479](https://github.com/matrix-org/matrix-spec/issues/1479))
+- Remove fictitious `token` parameter on `/keys/query` endpoint. ([#1485](https://github.com/matrix-org/matrix-spec/issues/1485))
+- Fix rendering of properties with a list of types. ([#1487](https://github.com/matrix-org/matrix-spec/issues/1487))
+- Clarify parts of the cross-signing signature upload request. ([#1495](https://github.com/matrix-org/matrix-spec/issues/1495))
+- Remove the `dont_notify` and `coalesce` push rule actions, as per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). ([#1501](https://github.com/matrix-org/matrix-spec/issues/1501))
+- Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks. ([#1507](https://github.com/matrix-org/matrix-spec/issues/1507))
+- Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. ([#1535](https://github.com/matrix-org/matrix-spec/issues/1535))
+
+
+### Server-Server API
+
+
+<strong>Spec Clarifications</strong>
+
+
+- Fix various typos throughout the specification. ([#1431](https://github.com/matrix-org/matrix-spec/issues/1431), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1466](https://github.com/matrix-org/matrix-spec/issues/1466), [#1518](https://github.com/matrix-org/matrix-spec/issues/1518))
+- Fix PDU examples by removing invalid OpenAPI reference to `examples/minimal_pdu.json`. ([#1454](https://github.com/matrix-org/matrix-spec/issues/1454))
+- Remove leftover `{key_id}` from `/_matrix/key/v2/server/`. ([#1473](https://github.com/matrix-org/matrix-spec/issues/1473))
+- Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536))
+
+
+### Application Service API
+
+
+<strong>New Endpoints</strong>
+
+
+- [`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516))
+- [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516))
+
+
+<strong>Backwards Compatible Changes</strong>
+
+
+- Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516), [#1541](https://github.com/matrix-org/matrix-spec/issues/1541))
+
+
+<strong>Spec Clarifications</strong>
+
+
+- Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447))
+
+
+### Identity Service API
+
+
+<strong>Spec Clarifications</strong>
+
+
+- Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486))
+
+
+### Push Gateway API
+
+
+No significant changes.
+
+
+### Room Versions
+
+
+<strong>Spec Clarifications</strong>
+
+
+- Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
+
+
+### Appendices
+
+
+<strong>Spec Clarifications</strong>
+
+
+- Clarify that the term "Canonical JSON" is a specific thing within the Matrix specification. ([#1468](https://github.com/matrix-org/matrix-spec/issues/1468))
+- Remove references to groups. ([#1483](https://github.com/matrix-org/matrix-spec/issues/1483))
+- Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
+
+
+### Internal Changes/Tooling
+
+
+<strong>Spec Clarifications</strong>
+
+
+- Update references to Inter font. ([#1444](https://github.com/matrix-org/matrix-spec/issues/1444))
+- Endpoint disclosures now hide everything but the URL. ([#1446](https://github.com/matrix-org/matrix-spec/issues/1446))
+- Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. ([#1457](https://github.com/matrix-org/matrix-spec/issues/1457))
+- Minor cleanups to the GitHub Actions workflows ([#1476](https://github.com/matrix-org/matrix-spec/issues/1476))
+- Fix generation of anchors for additional properties. ([#1488](https://github.com/matrix-org/matrix-spec/issues/1488))
+- Fix various typos throughout the specification. ([#1534](https://github.com/matrix-org/matrix-spec/issues/1534))
+- Document more of the spec release timeline/process. ([#1538](https://github.com/matrix-org/matrix-spec/issues/1538))
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@ -237,19 +237,32 @@ For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`
 would return a `200 OK` with the `event_id` of the original request in
 the response body.

-As well as the HTTP path, the scope of a transaction ID is a "client
-session", where that session is identified by a particular access token.
-When [refreshing](#refreshing-access-tokens) an access token, the
-transaction ID's scope is retained. This means that if a client with
-token `A` uses `TXN1` as their transaction ID, refreshes the token to
-`B`, and uses `TXN1` again it'll be assumed to be a duplicate request
-and ignored. If the client logs out and back in between the `A` and `B`
-tokens, `TXN1` could be used once for each.
+The scope of a transaction ID is for a single [device](../index.html#devices),
+and a single HTTP endpoint. In other words: a single device could use the same
+transaction ID for a request to [`PUT
+/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
+and [`PUT
+/_matrix/client/v3/sendToDevice/{eventType}/{txnId}`](#put_matrixclientv3sendtodeviceeventtypetxnid),
+and the two requests would be considered distinct because the two are
+considered separate endpoints. Similarly, if a client logs out and back in
+between two requests using the same transaction ID, the requests are distinct
+because the act of logging in and out creates a new device (unless an existing
+`device_id` is passed to [`POST
+/_matrix/client/v3/login`](#post_matrixclientv3login)). On the other hand, if a
+client re-uses a transaction ID for the same endpoint after
+[refreshing](#refreshing-access-tokens) an access token, it will be assumed to
+be a duplicate request and ignored. See also
+[Relationship between access tokens and devices](#relationship-between-access-tokens-and-devices).

 Some API endpoints may allow or require the use of `POST` requests
 without a transaction ID. Where this is optional, the use of a `PUT`
 request is strongly recommended.

+{{% boxes/rationale %}}
+Prior to `v1.7`, transaction IDs were scoped to "client sessions" rather than
+devices.
+{{% /boxes/rationale %}}
+
 ## Web Browser Clients

 It is realistic to expect that some clients will be written to be run
@ -1163,8 +1176,14 @@ client supports it, the client should redirect the user to the
 is complete, the client will need to submit a `/login` request matching
 `m.login.token`.

+{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
+a token for their user ID if supported by the homeserver using 
+[`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
+
 {{% http-api spec="client-server" api="login" %}}

+{{% http-api spec="client-server" api="login_token" %}}
+
 {{% http-api spec="client-server" api="refresh" %}}

 {{% http-api spec="client-server" api="logout" %}}
@ -2671,4 +2690,3 @@ systems.
 {{< cs-module name="event_annotations" >}}
 {{< cs-module name="threading" >}}
 {{< cs-module name="reference_relations" >}}
-
--- a/content/client-server-api/modules/event_annotations.md
+++ b/content/client-server-api/modules/event_annotations.md
@ -71,6 +71,12 @@ change their reaction, the original reaction should be redacted and a new one
 sent in its place.
 {{% /boxes/note %}}

+{{% boxes/note %}}
+The `key` field in `m.reaction` can be any string so clients must take care to
+render long reactions in a sensible manner. For example, clients can elide
+overly-long reactions.
+{{% /boxes/note %}}
+
 #### Server behaviour

 ##### Avoiding duplicate annotations
--- a/content/client-server-api/modules/event_replacements.md
+++ b/content/client-server-api/modules/event_replacements.md
@ -249,14 +249,14 @@ events](#redactions-of-edited-events) below.
 **Note:** the `content` of the original event is left intact. In particular servers
 should **not** replace the content with that of the replacement event.

-{{ boxes/rationale }}
+{{% boxes/rationale %}}
 In previous versions of the specification, servers were expected to replace the
 content of an edited event whenever it was served to clients (with the
 exception of the
 [`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid)
 endpoint).  However, that behaviour made reliable client-side implementation
 difficult, and servers should no longer make this replacement.
-{{ /boxes/rationale }}
+{{% /boxes/rationale %}}

 #### Client behaviour

@ -293,6 +293,73 @@ events will not be included in the aggregation bundled with the original
 event. Note that the subsequent edits are not actually redacted themselves:
 they simply serve no purpose within the visible timeline.

+#### Edits of events with mentions
+
+When editing an event with [user and room mentions](#user-and-room-mentions) the
+replacement event will have two `m.mentions` properties:
+
+* One at the top-level of the `content`, which should contain mentions due to
+  this edit revision.
+* One inside the `m.new_content` property, which should contain the resolved mentions
+  for the final version of the event.
+
+The difference between these properties ensures that users will not be notified
+for each edit revision of an event, but allows for new users to be mentioned (or
+for re-notifying if the sending client feels a large enough revision was made).
+
+For example, if there is an event mentioning Alice:
+
+```json5
+{
+    "event_id": "$original_event",
+    "type": "m.room.message",
+    "content": {
+        "body": "Hello Alice!",
+        "m.mentions": {
+            "user_ids": ["@alice:example.org"]
+        }
+    }
+}
+```
+
+And an edit to also mention Bob:
+
+```json5
+{
+  "content": {
+    "body": "* Hello Alice & Bob!",
+    "m.mentions": {
+      "user_ids": [
+        // Include only the newly mentioned user.
+        "@bob:example.org"
+      ]
+    },
+    "m.new_content": {
+      "body": "Hello Alice & Bob!",
+      "m.mentions": {
+        "user_ids": [
+          // Include all of the mentioned users.
+          "@alice:example.org",
+          "@bob:example.org"
+        ]
+      },
+    },
+    "m.relates_to": {
+      "rel_type": "m.replace",
+      "event_id": "$original_event"
+    }
+  },
+  // other fields as required by events
+}
+```
+
+If an edit revision removes a user's mention then that user's Matrix ID should be
+included in neither `m.mentions` property.
+
+Clients may also wish to modify the [client behaviour](#user-and-room-mentions) of
+determining if an event mentions the current user by checking the `m.mentions`
+property under `m.new_content`.
+
 #### Edits of replies

 Some particular constraints apply to events which replace a
--- a/content/client-server-api/modules/mentions.md
+++ b/content/client-server-api/modules/mentions.md
@ -1,61 +1,76 @@

 ### User and room mentions

-This module allows users to mention other users and rooms within a room message.
-This is achieved by including a [Matrix URI](/appendices/#uris) in the HTML body of
-an [m.room.message](#mroommessage) event. This module does not have any server-specific
-behaviour to it.
+{{% changed-in v="1.7" %}}

-Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is
-`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
-`org.matrix.custom.html` and therefore requires a `formatted_body`.
+This module allows users to "mention" other users and rooms within a room event.
+This is primarily used as an indicator that the recipient should receive a notification
+about the event.
+This is achieved by including metadata in the `m.mentions` content property of
+the event to reference the entity being mentioned.

-To make a mention, reference the entity being mentioned in the
-`formatted_body` using an anchor, like so:
+`m.mentions` is defined as follows:

-```json
-{
-    "body": "Hello Alice!",
-    "msgtype": "m.text",
-    "format": "org.matrix.custom.html",
-    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
-}
-```
+{{% definition path="api/client-server/definitions/m.mentions" %}}
+
+Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
+[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
+Users should not add their own Matrix ID to the `m.mentions` property as outgoing
+messages cannot self-notify.
+
+{{% boxes/warning %}}
+If an encrypted event contains an `m.mentions` in its payload, it should be
+encrypted as normal. To properly process mentions in encrypted rooms, events
+must be decrypted first. See [receiving notifications](#receiving-notifications).
+{{% /boxes/warning %}}
+
+Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
+[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
+[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to  match if the `body` of
+the event contains the user's display name or ID. To avoid unintentional notifications,
+**it is recommended that clients include a `m.mentions` property on each event**.
+(If there are no mentions to include it can be an empty object.)
+
+{{% boxes/rationale %}}
+In previous versions of the specification, mentioning users was done by
+including the user's display name or the localpart of their Matrix ID and room
+mentions were done by including the string "@room" in the plaintext `body` of
+the event. This was prone to confusing and buggy behaviour.
+{{% /boxes/rationale %}}

 #### Client behaviour

-In addition to using the appropriate `Matrix URI` for the mention,
-clients should use the following guidelines when making mentions in
-events to be sent:
+Although it is possible to silently mention users, it is recommended to include a
+[Matrix URI](/appendices/#uris) in the HTML body of  an [m.room.message](#mroommessage)
+event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is
+`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
+`org.matrix.custom.html` and therefore requires a `formatted_body`.

-   When mentioning users, use the user's potentially ambiguous display
+Clients should use the following guidelines when adding a `Matrix URI`
+representing a mention to events to be sent:
+
+-   When linking to users, use the user's potentially ambiguous display
    name for the anchor's text. If the user does not have a display
    name, use the user's ID.
-   When mentioning rooms, use the canonical alias for the room. If the
+-   When linking to rooms, use the canonical alias for the room. If the
    room does not have a canonical alias, prefer one of the aliases
    listed on the room. If no alias can be found, fall back to the room
    ID. In all cases, use the alias/room ID being linked to as the
    anchor's text.

 The text component of the anchor should be used in the event's `body`
-where the mention would normally be represented, as shown in the example
+where the link would normally be represented, as shown in the example
 above.

 Clients should display mentions differently from other elements. For
 example, this may be done by changing the background color of the
 mention to indicate that it is different from a normal link.

-If the current user is mentioned in a message (either by a mention as
-defined in this module or by a push rule), the client should show that
+If the current user is mentioned in a message, the client should show that
 mention differently from other mentions, such as by using a red
-background color to signify to the user that they were mentioned.
+background color to signify to the user that they were mentioned. Note that
+it is possible for a user to be mentioned without including their `Matrix URI`
+in the event.

 When clicked, the mention should navigate the user to the appropriate
 user or room information.
-
-{{% boxes/note %}}
-Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation),
-groups used to be representable by mentions. They follow a similar format
-to room mentions, though using the group ID in both the link and anchor
-text.
-{{% /boxes/note %}}
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@ -521,7 +521,46 @@ Definition:
 }
 ```

-**`.m.rule.contains_display_name`**
+<a id="_m_rule_is_user_mention"/> **`.m.rule.is_user_mention`**
+
+{{< added-in v="1.7" >}}
+
+Matches any message which contains the user's Matrix ID in the list of `user_ids`
+under the `m.mentions` property.
+
+Definition:
+
+```json
+{
+    "rule_id": ".m.rule.is_user_mention",
+    "default": true,
+    "enabled": true,
+    "conditions": [
+        {
+            "kind": "event_property_contains",
+            "key": "content.m\\.mentions.user_ids",
+            "value": "[the user's Matrix ID]"
+        }
+    ],
+    "actions": [
+        "notify",
+        {
+            "set_tweak": "sound",
+            "value": "default"
+        },
+        {
+            "set_tweak": "highlight"
+        }
+    ]
+}
+```
+
+<a id="_m_rule_contains_display_name"/> **`.m.rule.contains_display_name`**
+
+{{% changed-in v="1.7" %}}
+
+As of `v1.7`, this rule is deprecated and **should only be enabled if the event
+does not have an [`m.mentions` property](#definition-mmentions)**.

 Matches any message whose content contains the user's current display name
 in the room in which it was sent.
@ -551,7 +590,46 @@ Definition:
 }
 ```

-**`.m.rule.roomnotif`**
+<a id="_m_rule_is_room_mention"/> **`.m.rule.is_room_mention`**
+
+{{< added-in v="1.7" >}}
+
+Matches any message from a sender with the proper power level with the `room`
+property of the `m.mentions` property set to `true`.
+
+Definition:
+
+```json
+{
+    "rule_id": ".m.rule.is_room_mention",
+    "default": true,
+    "enabled": true,
+    "conditions": [
+        {
+            "kind": "event_property_is",
+            "key": "content.m\\.mentions.room",
+            "value": true
+        },
+        {
+            "kind": "sender_notification_permission",
+            "key": "room"
+        }
+    ],
+    "actions": [
+        "notify",
+        {
+            "set_tweak": "highlight"
+        }
+    ]
+}
+```
+
+<a id="_m_rule_roomnotif"/> **`.m.rule.roomnotif`**
+
+{{% changed-in v="1.7" %}}
+
+As of `v1.7`, this rule is deprecated and **should only be enabled if the event
+does not have an [`m.mentions` property](#definition-mmentions)**.

 Matches any message from a sender with the proper power level whose content
 contains the text `@room`, signifying the whole room should be notified of
@ -622,7 +700,7 @@ Definition:

 {{% added-in v="1.7" %}}

-Matches any event whose type is `m.room.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events.
+Matches any event whose type is `m.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events.

 Definition:

@ -674,7 +752,12 @@ Definition:

 ##### Default Content Rules

-**`.m.rule.contains_user_name`**
+<a id="_m_rule_contains_user_name"/> **`.m.rule.contains_user_name`**
+
+{{% changed-in v="1.7" %}}
+
+As of `v1.7`, this rule is deprecated and **should only be enabled if the event
+does not have an [`m.mentions` property](#definition-mmentions)**.

 Matches any message whose content contains the local part of the user's
 Matrix ID, separated by word boundaries.
--- a/content/client-server-api/modules/receipts.md
+++ b/content/client-server-api/modules/receipts.md
@ -153,12 +153,6 @@ relationships and solid lines showing topological ordering.

 ![threaded-dag](/diagrams/threaded-dag.png)

-{{% boxes/note %}}
-`m.reaction` relationships are not currently specified, but are shown here for
-their conceptual place in a threaded DAG. They are currently proposed as
-[MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677).
-{{% /boxes/note %}}
-
 This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread
 roots:

--- a/content/client-server-api/modules/rich_replies.md
+++ b/content/client-server-api/modules/rich_replies.md
@ -176,4 +176,34 @@ This is where the reply goes.

 For `m.image`, the text should be `"sent an image."`. For `m.video`, the
 text should be `"sent a video."`. For `m.audio`, the text should be
-`"sent an audio file"`.
+`"sent an audio file"`.
+
+#### Mentioning the replied to user
+
+In order to notify users of the reply, it may be desirable to include the `sender`
+of the replied to event and any users mentioned in that event. See
+[user and room mentions](#user-and-room-mentions) for additional information.
+
+An example including mentioning the original sender and other users:
+
+```json5
+{
+  "content": {
+    "m.relates_to": {
+      "m.in_reply_to": {
+        "event_id": "$another_event"
+      }
+    },
+    "body": "That sounds like a great idea!",
+    "m.mentions": {
+      "user_ids": [
+        // The sender of $another_event.
+        "@alice:example.org",
+        // Another Matrix ID copied from the m.mentions property of $another_event.
+        "@bob:example.org"
+      ]
+    }
+  },
+  // other fields as required by events
+}
+```
--- a/content/client-server-api/modules/voip_events.md
+++ b/content/client-server-api/modules/voip_events.md
@ -6,11 +6,128 @@ This module outlines how two users in a room can set up a Voice over IP
 WebRTC 1.0 standard. Call signalling is achieved by sending [message
 events](#events) to the room. In this version of the spec, only two-party
 communication is supported (e.g. between two peers, or between a peer
-and a multi-point conferencing unit). This means that clients MUST only
-send call events to rooms with exactly two participants.
+and a multi-point conferencing unit). Calls can take place in rooms with
+multiple members, but only two devices can take part in the call.
+
+All VoIP events have a `version` field. This is used to determine whether
+devices support this new version of the protocol. For example, clients can use
+this field to know whether to expect an `m.call.select_answer` event from their
+opponent. If clients see events with `version` other than `0` or `"1"`
+(including, for example, the numeric value `1`), they should treat these the
+same as if they had `version` == `"1"`.
+
+Note that this implies any and all future versions of VoIP events should be
+backwards-compatible.  If it does become necessary to introduce a non
+backwards-compatible VoIP spec, the intention would be for it to simply use a
+separate set of event types.
+
+#### Party Identifiers
+Whenever a client first participates in a new call, it generates a `party_id` for itself to use for the
+duration of the call. This needs to be long enough that the chance of a collision between multiple devices
+both generating an answer at the same time generating the same party ID is vanishingly small: 8 uppercase +
+lowercase alphanumeric characters is recommended. Parties in the call are identified by the tuple of
+`(user_id, party_id)`.
+
+The client  adds a `party_id` field containing this ID to the top-level of the content of all VoIP events
+it sends on the call, including `m.call.invite`. Clients use this to identify remote echo of their own
+events: since a user may call themselves, they cannot simply ignore events from their own user. This
+field also identifies different answers sent by different clients to an invite, and matches `m.call.candidates`
+events to their respective answer/invite.
+
+A client implementation may choose to use the device ID used in end-to-end cryptography for this purpose,
+or it may choose, for example, to use a different one for each call to avoid leaking information on which
+devices were used in a call (in an unencrypted room) or if a single device (ie. access token) were used to
+send signalling for more than one call party.
+
+A grammar for `party_id` is defined [below](#grammar-for-voip-ids).
+
+#### Politeness
+In line with [WebRTC perfect negotiation](https://w3c.github.io/webrtc-pc/#perfect-negotiation-example)
+there are rules to establish which party is polite in the process of renegotiation. The callee is
+always the polite party. In a glare situation, the politeness of a party is therefore determined by
+whether the inbound or outbound call is used: if a client discards its outbound call in favour of
+an inbound call, it becomes the polite party.
+
+#### Call Event Liveness
+`m.call.invite` contains a `lifetime` field that indicates how long the offer is valid for. When
+a client receives an invite, it should use the event's `age` field in the sync response plus the
+time since it received the event from the homeserver to determine whether the invite is still valid.
+The use of the `age` field ensures that incorrect clocks on client devices don't break calls.
+
+If the invite is still valid *and will remain valid for long enough for the user to accept the call*,
+it should signal an incoming call. The amount of time allowed for the user to accept the call may
+vary between clients. For example, it may be longer on a locked mobile device than on an unlocked
+desktop device.
+
+The client should only signal an incoming call in a given room once it has completed processing the
+entire sync response and, for encrypted rooms, attempted to decrypt all encrypted events in the
+sync response for that room. This ensures that if the sync response contains subsequent events that
+indicate the call has been hung up, rejected, or answered elsewhere, the client does not signal it.
+
+If on startup, after processing locally stored events, the client determines that there is an invite
+that is still valid, it should still signal it but only after it has completed a sync from the homeserver.
+
+The minimal recommended lifetime is 90 seconds - this should give the user enough time to actually pick
+up the call.
+
+#### ICE Candidate Batching
+Clients should aim to send a small number of candidate events, with guidelines:
+ * ICE candidates which can be discovered immediately or almost immediately in the invite/answer
+   event itself (eg. host candidates). If server reflexive or relay candidates can be gathered in
+   a sufficiently short period of time, these should be sent here too. A delay of around 200ms is
+   suggested as a starting point.
+ * The client should then allow some time for further candidates to be gathered in order to batch them,
+   rather than sending each candidate as it arrives. A starting point of 2 seconds after sending the
+   invite or 500ms after sending the answer is suggested as a starting point (since a delay is natural
+   anyway after the invite whilst the client waits for the user to accept it).
+
+#### End-of-candidates
+An ICE candidate whose value is the empty string means that no more ICE candidates will
+be sent. Clients must send such a candidate in an `m.call.candidates` message.
+The WebRTC spec requires browsers to generate such a candidate, however note that at time of writing,
+not all browsers do (Chrome does not, but does generate an `icegatheringstatechange` event). The
+client should send any remaining candidates once candidate generation finishes, ignoring timeouts above.
+This allows bridges to batch the candidates together when bridging to protocols that don't support
+trickle ICE.
+
+#### DTMF
+Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of August
+2020 does not support receiving DTMF but a Matrix client can receive and interpret the DTMF sent
+in the RTP payload.
+
+#### Grammar for VoIP IDs
+`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting
+of the characters `[0-9a-zA-Z._~-]`.
+
+(Note that this matches the grammar of 'opaque IDs' from
+[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids),
+and that of the `id` property of the
+ [`m.login.sso` flow schema](#definition-mloginsso-flow-schema).)
+
+#### Behaviour on Room Leave
+If the client sees the user it is in a call with leave the room, the client should treat this
+as a hangup event for any calls that are in progress. No specific requirement is given for the
+situation where a client has sent an invite and the invitee leaves the room, but the client may
+wish to treat it as a rejection if there are no more users in the room who could answer the call
+(eg. the user is now alone or the `invitee` field was set on the invite).
+
+The same behaviour applies when a client is looking at historic calls.
+
+#### Supported Codecs
+The Matrix spec does not mandate particular audio or video codecs, but instead defers to the
+WebRTC spec. A compliant Matrix VoIP client will behave in the same way as a supported 'browser'
+in terms of what codecs it supports and what variants thereof. The latest WebRTC specification
+applies, so clients should keep up to date with new versions of the WebRTC specification whether
+or not there have been any changes to the Matrix spec.

 #### Events

+##### Common Fields
+
+{{% event-fields event_type="call_event" %}}
+
+##### Events
+
 {{% event-group group_name="m.call" %}}

 #### Client behaviour
@ -25,6 +142,7 @@ A call is set up with message events exchanged as follows:
    [..candidates..] -------->
                            [Answers call]
           <--------------- m.call.answer
+    m.call.select_answer ----------->
     [Call is active and ongoing]
           <--------------- m.call.hangup
 ```
@ -42,6 +160,43 @@ Or a rejected call:

 Calls are negotiated according to the WebRTC specification.

+In response to an incoming invite, a client may do one of several things:
+ * Attempt to accept the call by sending an `m.call.answer`.
+ * Actively reject the call everywhere: send an `m.call.reject` as per above, which will stop the call from
+   ringing on all the user's devices and the caller's client will inform them that the user has
+   rejected their call.
+ * Ignore the call: send no events, but stop alerting the user about the call. The user's other
+   devices will continue to ring, and the caller's device will continue to indicate that the call
+   is ringing, and will time the call out in the normal way if no other device responds.
+
+##### Streams
+
+Clients are expected to send one stream with one track of kind `audio` (creating a
+voice call). They can optionally send a second track in the same stream of kind
+`video` (creating a video call).
+
+Clients implementing this specification use the first stream and will ignore
+any streamless tracks. Note that in the JavaScript WebRTC API, this means
+`addTrack()` must be passed two parameters: a track and a stream, not just a
+track, and in a video call the stream must be the same for both audio and video
+track.
+
+A client may send other streams and tracks but the behaviour of the other party
+with respect to presenting such streams and tracks is undefined.
+
+##### Invitees
+The `invitee` field should be added whenever the call is intended for one
+specific user, and should be set to the Matrix user ID of that user. Invites
+without an `invitee` field are defined to be intended for any member of the
+room other than the sender of the event.
+
+Clients should consider an incoming call if they see a non-expired invite event where the `invitee` field is either
+absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their
+user's trust relationship with the callers and/or where the call was placed. As a starting point, it is
+suggested that clients ignore call invites from users in public rooms. It is strongly recommended that
+when clients do not ring for an incoming call invite, they still display the call invite in the room and
+annotate that it was ignored.
+
 ##### Glare

 "Glare" is a problem which occurs when two users call each other at
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@ -1270,7 +1270,7 @@ specification](/rooms) for more information. It is
 calculated as follows.

 1.  The event is put through the redaction algorithm.
-2.  The `signatures`, `age_ts`, and `unsigned` properties are removed
+2.  The `signatures` and `unsigned` properties are removed
    from the event, if present.
 3.  The event is converted into [Canonical
    JSON](/appendices#canonical-json).
--- a/data/api/application-service/ping.yaml
+++ b/data/api/application-service/ping.yaml
@ -0,0 +1,72 @@
+# Copyright 2023 Tulir Asokan
+#
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Application Service API
+  version: 1.0.0
+paths:
+  /ping:
+    post:
+      x-addedInMatrixVersion: "1.7"
+      summary: Ping the application service
+      description: |-
+        This API is called by the homeserver to ensure that the connection works
+        and the `hs_token` the homeserver has is correct.
+
+        Currently this is only called by the homeserver as a direct result of
+        the application service calling
+        [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping).
+      operationId: ping
+      security:
+        - homeserverAccessToken: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "transaction_id": "mautrix-go_1683636478256400935_123"
+              }
+              properties:
+                transaction_id:
+                  type: string
+                  description: |-
+                    A transaction ID for the ping, copied directly from the
+                    `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
+        description: Ping body with optional transaction ID.
+      responses:
+        "200":
+          description: The provided `hs_token` is valid and the ping request was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/app/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml
--- a/data/api/client-server/appservice_ping.yaml
+++ b/data/api/client-server/appservice_ping.yaml
@ -0,0 +1,182 @@
+# Copyright 2023 Tulir Asokan
+#
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Application Service Ping API
+  version: 1.0.0
+paths:
+  "/appservice/{appserviceId}/ping":
+    post:
+      x-addedInMatrixVersion: "1.7"
+      summary: Ask the homeserver to ping the application service to ensure the
+        connection works.
+      description: |-
+        This API asks the homeserver to call the
+        [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
+        application service to ensure that the homeserver can communicate
+        with the application service.
+
+        This API requires the use of an application service access token (`as_token`)
+        instead of a typical client's access token. This API cannot be invoked by
+        users who are not identified as application services. Additionally, the
+        appservice ID in the path must be the same as the appservice whose `as_token`
+        is being used.
+      operationId: pingAppservice
+      parameters:
+        - in: path
+          name: appserviceId
+          description: |-
+            The appservice ID of the appservice to ping. This must be the same
+            as the appservice whose `as_token` is being used to authenticate the
+            request.
+          required: true
+          example: telegram
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                transaction_id:
+                  type: string
+                  description: An optional transaction ID that is passed through to the
+                    `/_matrix/app/v1/ping` call.
+                  example: mautrix-go_1683636478256400935_123
+        required: true
+      security:
+        # again, this is the appservice's token - not a typical client's
+        - accessToken: []
+      responses:
+        "200":
+          description: The ping was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  duration_ms:
+                    type: integer
+                    description: |-
+                      The duration in milliseconds that the
+                      [`/_matrix/app/v1/ping`](#post_matrixappv1ping)
+                      request took from the homeserver's point of view.
+                required:
+                  - duration_ms
+              examples:
+                response:
+                  value: {
+                    "duration_ms": 123
+                  }
+        "400":
+          description: The application service doesn't have a URL configured. The errcode
+            is `M_URL_NOT_SET`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_URL_NOT_SET",
+                    "error": "Application service doesn't have a URL configured"
+                  }
+        "403":
+          description: The access token used to authenticate the request doesn't belong to
+            an appservice, or belongs to a different appservice than the one in
+            the path. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Provided access token is not the appservice's as_token"
+                  }
+        "502":
+          description: |-
+            The application service returned a bad status, or the connection failed.
+            The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
+
+            For bad statuses, the response may include `status` and `body`
+            fields containing the HTTP status code and response body text
+            respectively to aid with debugging.
+          content:
+            application/json:
+              schema:
+                type: object
+                title: Error
+                description: A Matrix-level Error
+                properties:
+                  errcode:
+                    type: string
+                    description: An error code.
+                    enum:
+                      - M_BAD_STATUS
+                      - M_CONNECTION_FAILED
+                  error:
+                    type: string
+                    description: A human-readable error message.
+                    example: Ping returned status 401
+                  status:
+                    type: integer
+                    description: The HTTP status code returned by the appservice.
+                    example: 401
+                  body:
+                    type: string
+                    description: The HTTP response body returned by the appservice.
+                    example: '{"errcode": "M_UNKNOWN_TOKEN"}'
+                required:
+                  - errcode
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_BAD_STATUS",
+                    "error": "Ping returned status 401",
+                    "status": 401,
+                    "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
+                  }
+        "504":
+          description: The connection to the application service timed out. The errcode is
+            `M_CONNECTION_TIMEOUT`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_CONNECTION_TIMEOUT",
+                    "error": "Connection to application service timed out"
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    # Note: this is the same access_token definition used elsewhere in the client
+    # server API, however this expects an access token for an application service.
+    $ref: definitions/security.yaml
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@ -219,7 +219,7 @@ paths:
      summary: Create a new `mxc://` URI without uploading the content.
      description: |-
        Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later
-        via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](http://localhost:1313/client-server-api/#put_matrixmediav3uploadservernamemediaid).
+        via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid).

        The server may optionally enforce a maximum age for unused IDs,
        and delete media IDs when the client doesn't start the upload in time,
@ -242,7 +242,6 @@ paths:
      security:
        - accessToken: []
      # empty json object
-      parameters: []
      responses:
        "200":
          description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for
@ -335,6 +334,18 @@ paths:
            type: integer
            format: int64
            default: 20000
+        - in: query
+          name: allow_redirect
+          x-addedInMatrixVersion: "1.7"
+          required: false
+          description: |
+            Indicates to the server that it may return a 307 or 308 redirect response that points
+            at the relevant media content. When not explicitly set to true the server must return
+            the media content itself.
+          example: false
+          schema:
+            type: boolean
+            default: false
      responses:
        "200":
          description: The content that was previously uploaded.
@ -353,6 +364,21 @@ paths:
                type: string
                # This is a workaround for us not being able to say the response is required.
                description: "**Required.** The bytes for the uploaded file."
+                format: binary
+        "307":
+          description: A redirect to the thumbnail of the requested content.
+          headers:
+            Location:
+              description: The URL of the thumbnail content.
+              schema:
+                type: string
+        "308":
+          description: A redirect to the thumbnail of the requested content.
+          headers:
+            Location:
+              description: The URL of the thumbnail content.
+              schema:
+                type: string
        "429":
          description: This request was rate-limited.
          content:
@ -445,6 +471,18 @@ paths:
            type: integer
            format: int64
            default: 20000
+        - in: query
+          name: allow_redirect
+          x-addedInMatrixVersion: "1.7"
+          required: false
+          description: |
+            Indicates to the server that it may return a 307 or 308 redirect response that points
+            at the relevant media content. When not explicitly set to true the server must return
+            the media content itself.
+          example: false
+          schema:
+            type: boolean
+            default: false
      responses:
        "200":
          description: The content that was previously uploaded.
@ -466,6 +504,20 @@ paths:
                # This is a workaround for us not being able to say the response is required.
                description: "**Required.** The bytes for the uploaded file."
                format: binary
+        "307":
+          description: A redirect to the thumbnail of the requested content.
+          headers:
+            Location:
+              description: The URL of the thumbnail content.
+              schema:
+                type: string
+        "308":
+          description: A redirect to the thumbnail of the requested content.
+          headers:
+            Location:
+              description: The URL of the thumbnail content.
+              schema:
+                type: string
        "429":
          description: This request was rate-limited.
          content:
@ -579,6 +631,18 @@ paths:
            type: integer
            format: int64
            default: 20000
+        - in: query
+          name: allow_redirect
+          x-addedInMatrixVersion: "1.7"
+          required: false
+          description: |
+            Indicates to the server that it may return a 307 or 308 redirect response that points
+            at the relevant media content. When not explicitly set to true the server must return
+            the media content itself.
+          example: false
+          schema:
+            type: boolean
+            default: false
      responses:
        "200":
          description: A thumbnail of the requested content.
@ -600,9 +664,22 @@ paths:
            image/png:
              schema:
                type: string
-                # This is a workaround for us not being able to say the response is required.
                description: "**Required.** The bytes for the thumbnail."
                format: binary
+        "307":
+          description: A redirect to the thumbnail of the requested content.
+          headers:
+            Location:
+              description: The URL of the thumbnail content.
+              schema:
+                type: string
+        "308":
+          description: A redirect to the thumbnail of the requested content.
+          headers:
+            Location:
+              description: The URL of the thumbnail content.
+              schema:
+                type: string
        "400":
          description: |-
            The request does not make sense to the server, or the server cannot thumbnail
--- a/data/api/client-server/definitions/m.mentions.yaml
+++ b/data/api/client-server/definitions/m.mentions.yaml
@ -0,0 +1,37 @@
+# Copyright 2023 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: m.mentions
+description: |-
+  Describes whether the event mentions other users or the room. This is contained
+  within the event's `content` alongside other fields for the relevant event type.
+example: {
+    "body": "Hello Alice!",
+    "msgtype": "m.text",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
+    "m.mentions": {
+        "user_ids": ["@alice:example.org"]
+    }
+}
+properties:
+  user_ids:
+    type: string[]
+    description: A list of Matrix IDs of mentioned users.
+  room:
+    type: boolean
+    description: |-
+      A boolean set to `true` to mention the room, for an `@room` notification.
+      (`room` should otherwise not be included on the event.)
--- a/data/api/client-server/login.yaml
+++ b/data/api/client-server/login.yaml
@ -39,18 +39,34 @@ paths:
                    items:
                      type: object
                      title: LoginFlow
+                      required:
+                        - type
                      properties:
                        type:
                          description: |-
                            The login type. This is supplied as the `type` when
                            logging in.
                          type: string
+                        get_login_token:
+                          type: boolean
+                          x-addedInMatrixVersion: "1.7"
+                          description: |-
+                            If `type` is `m.login.token`, an optional field to indicate
+                            to the unauthenticated client that the homeserver supports
+                            the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token)
+                            endpoint. Note that supporting the endpoint does not
+                            necessarily indicate that the user attempting to log in will
+                            be able to generate such a token.
              examples:
                response:
                  value: {
                    "flows": [
                      {
                        "type": "m.login.password"
+                      },
+                      {
+                        "type": "m.login.token",
+                        "get_login_token": true
                      }
                    ]
                  }
--- a/data/api/client-server/login_token.yaml
+++ b/data/api/client-server/login_token.yaml
@ -0,0 +1,134 @@
+# Copyright 2023 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Registration and Login API
+  version: 1.0.0
+paths:
+  /login/get_token:
+    post:
+      summary: Optional endpoint to generate a single-use, time-limited,
+        `m.login.token` token.
+      description: |-
+        Optional endpoint - the server is not required to implement this endpoint if it does not
+        intend to use or support this functionality.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+        An already-authenticated client can call this endpoint to generate a single-use, time-limited,
+        token for an unauthenticated client to log in with, becoming logged in as the same user which
+        called this endpoint. The unauthenticated client uses the generated token in a `m.login.token`
+        login flow with the homeserver.
+
+        Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes
+        this feature if the server is not offering it. Authenticated clients can check for support on
+        a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation),
+        while unauthenticated clients can detect server support by looking for an `m.login.token` login
+        flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login).
+
+        In v1.7 of the specification, transmission of the generated token to an unauthenticated client is
+        left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906)
+        might standarise a way to transmit the token between clients.
+
+        The generated token MUST only be valid for a single login, enforced by the server. Clients which
+        intend to log in multiple devices must generate a token for each.
+
+        With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt
+        for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt
+        the user for verification to ensure explicit consent is gained for each additional client.
+
+        Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum
+        of 1 request per minute.
+      operationId: generateLoginToken
+      x-addedInMatrixVersion: "1.7"
+      security:
+        - accessToken: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+        required: true
+      responses:
+        "200":
+          description: The login token an unauthenticated client can use to log in as the
+            requesting user.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - login_token
+                  - expires_in_ms
+                properties:
+                  login_token:
+                    type: string
+                    description: The login token for the `m.login.token` login flow.
+                  expires_in_ms:
+                    type: integer
+                    description: |-
+                      The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
+                      (2 minutes) is recommended as a default.
+              examples:
+                response:
+                  value: {
+                    "login_token": "<opaque string>",
+                    "expires_in_ms": 120000
+                  }
+        "400":
+          description: |-
+            The request was malformed, or the user does not have an ability to generate tokens for their devices,
+            as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+            Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token`
+            [capability](/client-server-api/#capabilities-negotiation).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Session management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml
--- a/data/api/server-server/events.yaml
+++ b/data/api/server-server/events.yaml
@ -140,6 +140,20 @@ paths:
                required:
                  - auth_chain_ids
                  - pdu_ids
+        "404":
+          description: |-
+            The given `event_id` was not found or the server doesn't know about the state at
+            that event to return anything useful.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg"
+                  }
  "/event/{eventId}":
    get:
      summary: Get a single event
--- a/data/api/server-server/joins-v1.yaml
+++ b/data/api/server-server/joins-v1.yaml
@ -225,6 +225,7 @@ paths:
                  }
  "/send_join/{roomId}/{eventId}":
    put:
+      deprecated: true
      summary: Submit a signed join event to a resident server
      description: |-
        **Note:**
@ -319,18 +320,6 @@ paths:
                - origin_server_ts
                - type
                - content
-            example: {
-              "room_id": "!somewhere:example.org",
-              "type": "m.room.member",
-              "state_key": "@someone:example.org",
-              "origin": "example.org",
-              "origin_server_ts": 1549041175876,
-              "sender": "@someone:example.org",
-              "content": {
-                  "membership": "join",
-                  "join_authorised_via_users_server": "@anyone:resident.example.org"
-              }
-            }
        required: true
      responses:
        "200":
--- a/data/api/server-server/keys_query.yaml
+++ b/data/api/server-server/keys_query.yaml
@ -88,7 +88,6 @@ paths:
                    given.
                  additionalProperties:
                    type: object
-                    title: ServerName
                    description: The server names to query.
                    additionalProperties:
                      type: object
--- a/data/api/server-server/leaving-v1.yaml
+++ b/data/api/server-server/leaving-v1.yaml
@ -140,6 +140,7 @@ paths:
                  }
  "/send_leave/{roomId}/{eventId}":
    put:
+      deprecated: true
      summary: Submit a signed leave event to a resident server
      description: |-
        **Note:**
@ -222,17 +223,6 @@ paths:
                - type
                - depth
                - content
-            example: {
-              "room_id": "!somewhere:example.org",
-              "type": "m.room.member",
-              "state_key": "@someone:example.org",
-              "origin": "example.org",
-              "origin_server_ts": 1549041175876,
-              "sender": "@someone:example.org",
-              "content": {
-                  "membership": "leave"
-              }
-            }
        required: true
      responses:
        "200":
--- a/data/event-schemas/examples/m.call.answer.yaml
+++ b/data/event-schemas/examples/m.call.answer.yaml
@ -2,7 +2,8 @@
  "$ref": "core/room_event.json",
  "type": "m.call.answer",
  "content": {
-    "version" : 0,
+    "version" : "1",
+    "party_id": "67890",
    "call_id": "12345",
    "answer": {
      "type" : "answer",
--- a/data/event-schemas/examples/m.call.candidates.yaml
+++ b/data/event-schemas/examples/m.call.candidates.yaml
@ -2,7 +2,8 @@
  "$ref": "core/room_event.json",
  "type": "m.call.candidates",
  "content": {
-    "version" : 0,
+    "version" : "1",
+    "party_id": "67890",
    "call_id": "12345",
    "candidates": [
      {
--- a/data/event-schemas/examples/m.call.hangup.yaml
+++ b/data/event-schemas/examples/m.call.hangup.yaml
@ -2,7 +2,9 @@
  "$ref": "core/room_event.json",
  "type": "m.call.hangup",
  "content": {
-    "version" : 0,
-    "call_id": "12345"
+    "version" : "1",
+    "party_id": "67890",
+    "call_id": "12345",
+    "reason": "user_hangup"
  }
 }
--- a/data/event-schemas/examples/m.call.invite.yaml
+++ b/data/event-schemas/examples/m.call.invite.yaml
@ -2,7 +2,8 @@
  "$ref": "core/room_event.json",
  "type": "m.call.invite",
  "content": {
-    "version" : 0,
+    "version" : "1",
+    "party_id": "67890",
    "call_id": "12345",
    "lifetime": 60000,
    "offer": {
--- a/data/event-schemas/examples/m.call.negotiate.yaml
+++ b/data/event-schemas/examples/m.call.negotiate.yaml
@ -0,0 +1,14 @@
+{
+  "$ref": "core/room_event.json",
+  "type": "m.call.negotiate",
+  "content": {
+    "version" : "1",
+    "party_id": "67890",
+    "call_id": "12345",
+    "lifetime": 10000,
+    "offer": {
+      "type" : "offer",
+      "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
+    }
+  }
+}
--- a/data/event-schemas/examples/m.call.reject.yaml
+++ b/data/event-schemas/examples/m.call.reject.yaml
@ -0,0 +1,9 @@
+{
+  "$ref": "core/room_event.json",
+  "type": "m.call.reject",
+  "content": {
+    "version" : "1",
+    "party_id": "67890",
+    "call_id": "12345"
+  }
+}
--- a/data/event-schemas/examples/m.call.select_answer.yaml
+++ b/data/event-schemas/examples/m.call.select_answer.yaml
@ -0,0 +1,10 @@
+{
+  "$ref": "core/room_event.json",
+  "type": "m.call.select_answer",
+  "content": {
+    "version" : "1",
+    "call_id": "12345",
+    "party_id": "67890",
+    "selected_party_id": "111213"
+  }
+}
--- a/data/event-schemas/schema/core-event-schema/call_event.yaml
+++ b/data/event-schemas/schema/core-event-schema/call_event.yaml
@ -0,0 +1,25 @@
+description: "The content of all call events shares a set of common fields: those
+  of room events and some additional VoIP specific fields."
+properties:
+  call_id:
+    type: string
+    description: The ID of the call this event relates to.
+  version:
+    type: string
+    description: The version of the VoIP specification this message adheres to.
+      This specification is version 1. This field is a string such that experimental
+      implementations can use non-integer versions. This field was an integer
+      in the previous spec version and implementations must accept an integer
+      0.
+  party_id:
+    type: string
+    description: 'This identifies the party that sent this event. A client may
+      choose to re-use the device ID from end-to-end cryptography for the value
+      of this field.'
+    x-addedInMatrixVersion: "1.7"
+required:
+- call_id
+- version
+- party_id
+title: CallEvent
+type: object
--- a/data/event-schemas/schema/m.call.answer.yaml
+++ b/data/event-schemas/schema/m.call.answer.yaml
@ -7,11 +7,10 @@
    "properties": {
        "content": {
            "type": "object",
+            "allOf": [{
+                "$ref": "core-event-schema/call_event.yaml"
+            }],
            "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "The ID of the call this event relates to."
-                },
                "answer": {
                    "type": "object",
                    "title": "Answer",
@ -28,13 +27,9 @@
                        }
                    },
                    "required": ["type", "sdp"]
-                },
-                "version": {
-                    "type": "number",
-                    "description": "The version of the VoIP specification this messages adheres to. This specification is version 0."
                }
            },
-            "required": ["call_id", "answer", "version"]
+            "required": ["answer"]
        },
        "type": {
            "type": "string",
--- a/data/event-schemas/schema/m.call.candidates.yaml
+++ b/data/event-schemas/schema/m.call.candidates.yaml
@ -7,11 +7,10 @@
    "properties": {
        "content": {
            "type": "object",
+            "allOf": [{
+                "$ref": "core-event-schema/call_event.yaml"
+            }],
            "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "The ID of the call this event relates to."
-                },
                "candidates": {
                    "type": "array",
                    "description": "Array of objects describing the candidates.",
@ -34,13 +33,9 @@
                        },
                        "required": ["candidate", "sdpMLineIndex", "sdpMid"]
                    }
-                },
-                "version": {
-                    "type": "integer",
-                    "description": "The version of the VoIP specification this messages adheres to. This specification is version 0."
                }
            },
-            "required": ["call_id", "candidates", "version"]
+            "required": ["candidates"]
        },
        "type": {
            "type": "string",
--- a/data/event-schemas/schema/m.call.hangup.yaml
+++ b/data/event-schemas/schema/m.call.hangup.yaml
@ -1,35 +1,54 @@
-{
-    "type": "object",
-    "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.",
-    "allOf": [{
-        "$ref": "core-event-schema/room_event.yaml"
-    }],
-    "properties": {
-        "content": {
-            "type": "object",
-            "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "The ID of the call this event relates to."
-                },
-                "version": {
-                    "type": "integer",
-                    "description": "The version of the VoIP specification this message adheres to. This specification is version 0."
-                },
-                "reason": {
-                    "type": "string",
-                    "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or `invite_timeout` for when the other party did not answer in time.",
-                    "enum": [
-                        "ice_failed",
-                        "invite_timeout"
-                    ]
-                }
-            },
-            "required": ["call_id", "version"]
-        },
-        "type": {
-            "type": "string",
-            "enum": ["m.call.hangup"]
-        }
-    }
-}
+---
+type: object
+description: |
+  Sent by either party to signal their termination of the call. This can
+  be sent either once the call has has been established or before to abort the call.
+
+  The meanings of the `reason` field are as follows:
+   * `ice_failed`: ICE negotiation has failed and a media connection could not be established.
+   * `ice_timeout`: The connection failed after some media was exchanged (as opposed to `ice_failed`
+      which means no media connection could be established). Note that, in the case of an ICE
+      renegotiation, a client should be sure to send `ice_timeout` rather than `ice_failed` if media
+      had previously been received successfully, even if the ICE renegotiation itself failed.
+   * `invite_timeout`: The other party did not answer in time.
+   * `user_hangup`: Clients must now send this code when the user chooses to end the call, although
+     for backwards compatibility with version 0, a clients should treat an absence of the `reason`
+     field as `user_hangup`.
+   * `user_media_failed`: The client was unable to start capturing media in such a way that it is unable
+     to continue the call.
+   * `user_busy`: The user is busy. Note that this exists primarily for bridging to other networks such
+      as the PSTN. A Matrix client that receives a call whilst already in a call would not generally reject
+      the new call unless the user had specifically chosen to do so.
+   * `unknown_error`: Some other failure occurred that meant the client was unable to continue the call
+      rather than the user choosing to end it.
+allOf:
+- "$ref": core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - "$ref": core-event-schema/call_event.yaml
+    properties:
+      reason:
+        type: string
+        description: Reason for the hangup. Note that this was optional in
+          previous previous versions of the spec, so a missing value should be
+          treated as `user_hangup`.
+        x-changedInMatrixVersion:
+          1.7: |-
+            Additional values were added.
+        enum:
+        - ice_timeout
+        - ice_failed
+        - invite_timeout
+        - user_hangup
+        - user_media_failed
+        - user_busy
+        - unknown_error
+    required:
+    - reason
+  type:
+    type: string
+    enum:
+    - m.call.hangup
+
--- a/data/event-schemas/schema/m.call.invite.yaml
+++ b/data/event-schemas/schema/m.call.invite.yaml
@ -7,11 +7,10 @@
    "properties": {
        "content": {
            "type": "object",
+            "allOf": [{
+                "$ref": "core-event-schema/call_event.yaml"
+            }],
            "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "A unique identifier for the call."
-                },
                "offer": {
                    "type": "object",
                    "title": "Offer",
@ -29,16 +28,17 @@
                    },
                    "required": ["type", "sdp"]
                },
-                "version": {
-                    "type": "integer",
-                    "description": "The version of the VoIP specification this message adheres to. This specification is version 0."
-                },
                "lifetime": {
                    "type": "integer",
                    "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI."
+                },
+                "invitee": {
+                    "type": "string",
+                    "description": "The ID of the user being called. If omitted, any user in the room can answer.",
+                    "x-addedInMatrixVersion": "1.7",
                }
            },
-            "required": ["call_id", "offer", "version", "lifetime"]
+            "required": ["offer", "lifetime"]
        },
        "type": {
            "type": "string",
--- a/data/event-schemas/schema/m.call.negotiate.yaml
+++ b/data/event-schemas/schema/m.call.negotiate.yaml
@ -0,0 +1,74 @@
+---
+type: object
+description: |
+  Provides SDP negotiation semantics for media pause, hold/resume, ICE restarts
+  and voice/video call up/downgrading. Clients should implement and honour hold
+  functionality as per [WebRTC's recommendation](https://www.w3.org/TR/webrtc/#hold-functionality).
+
+  If both the invite event and the accepted answer event have `version` equal
+  to `"1"`, either party may send `m.call.negotiate` with a `description` field
+  to offer new SDP to the other party. This event has `call_id` with the ID of
+  the call and `party_id` equal to the client's party ID for that call.  The
+  caller ignores any negotiate events with `party_id` + `user_id` tuple not
+  equal to that of the answer it accepted and the callee ignores any negotiate
+  events with `party_id` + `user_id` tuple not equal to that of the caller.
+  Clients should use the `party_id` field to ignore the remote echo of their
+  own negotiate events.
+
+  This has a `lifetime` field as in `m.call.invite`, after which the sender of
+  the negotiate event should consider the negotiation failed (timed out) and
+  the recipient should ignore it.
+
+  The `description` field is the same as the `offer` field in `m.call.invite`
+  and `answer` field in `m.call.answer` and is an `RTCSessionDescriptionInit`
+  object as per https://www.w3.org/TR/webrtc/#dom-rtcsessiondescriptioninit.
+
+  Once an `m.call.negotiate` event is received, the client must respond with
+  another `m.call.negotiate` event, with the SDP answer (with `"type": "answer"`)
+  in the `description` property.
+
+  In the `m.call.invite` and `m.call.answer` events, the `offer` and `answer`
+  fields respectively are objects of type `RTCSessionDescriptionInit`.  Hence
+  the `type` field, whilst redundant in these events, is included for ease of
+  working with the WebRTC API and is mandatory. Receiving clients should not
+  attempt to validate the `type` field, but simply pass the object into the
+  WebRTC API.
+x-addedInMatrixVersion: "1.7"
+allOf:
+- "$ref": core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - "$ref": core-event-schema/call_event.yaml
+    properties:
+      offer:
+        type: object
+        title: Offer
+        description: The session description object
+        properties:
+          type:
+            type: string
+            enum:
+            - offer
+            description: The type of session description.
+          sdp:
+            type: string
+            description: The SDP text of the session description.
+        required:
+        - type
+        - sdp
+      lifetime:
+        type: integer
+        description: The time in milliseconds that the invite is valid for.
+          Once the invite age exceeds this value, clients should discard it.
+          They should also no longer show the call as awaiting an answer in the
+          UI.
+    required:
+    - offer
+    - lifetime
+  type:
+    type: string
+    enum:
+    - m.call.negotiate
+
--- a/data/event-schemas/schema/m.call.reject.yaml
+++ b/data/event-schemas/schema/m.call.reject.yaml
@ -0,0 +1,28 @@
+---
+type: object
+description: |
+  If the `m.call.invite` event has `version` `"1"`, a client wishing to
+  reject the call sends an `m.call.reject` event. This rejects the call on all devices,
+  but if the calling device sees an `answer` before the `reject`, it disregards the
+  reject event and carries on. The reject has a `party_id` just like an answer, and
+  the caller sends a `select_answer` for it just like an answer. If another client
+  had already sent an answer and sees the caller select the reject response instead
+  of its answer, it ends the call. If the `m.call.invite` event has `version` `0`,
+  the callee sends an `m.call.hangup` event. If the calling user chooses to end the
+  call before setup is complete, the client sends `m.call.hangup` as previously.
+
+  Note that, unlike `m.call.hangup`, this event has no `reason` field: the rejection of
+  a call is always implicitly because the user chose not to answer it.
+x-addedInMatrixVersion: "1.7"
+allOf:
+- "$ref": core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - "$ref": core-event-schema/call_event.yaml
+  type:
+    type: string
+    enum:
+    - m.call.reject
+
--- a/data/event-schemas/schema/m.call.select_answer.yaml
+++ b/data/event-schemas/schema/m.call.select_answer.yaml
@ -0,0 +1,27 @@
+{
+    "type": "object",
+    "description": "This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming `m.call.answer` events. Its `selected_party_id` field indicates the answer it's chosen. The `call_id` and `party_id` of the caller is also included. If the callee's client sees a `select_answer` for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent.  Clients that implement previous versions of this specification will ignore this event and behave as they did before.",
+    "x-addedInMatrixVersion": "1.7",
+    "allOf": [{
+        "$ref": "core-event-schema/room_event.yaml"
+    }],
+    "properties": {
+        "content": {
+            "type": "object",
+            "allOf": [{
+                "$ref": "core-event-schema/call_event.yaml"
+            }],
+            "properties": {
+                "selected_party_id": {
+                    "type": "string",
+                    "description": "The `party_id` field from the answer event that the caller chose."
+                },
+            },
+            "required": ["selected_party_id"]
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.call.select_answer"]
+        }
+    }
+}
--- a/data/event-schemas/schema/m.reaction.yaml
+++ b/data/event-schemas/schema/m.reaction.yaml
@ -30,8 +30,10 @@ properties:
          key:
            type: string
            description: |-
-              An emoji representing the reaction being made. Should include the
-              unicode emoji presentation selector (`\uFE0F`) for codepoints
-              which allow it (see the [emoji variation sequences
+              The reaction being made, usually an emoji.
+
+              If this is an emoji, it should include the unicode emoji
+              presentation selector (`\uFE0F`) for codepoints which allow it
+              (see the [emoji variation sequences
              list](https://www.unicode.org/Public/UCD/latest/ucd/emoji/emoji-variation-sequences.txt)).
            example: "👍"
--- a/data/event-schemas/schema/m.room.join_rules.yaml
+++ b/data/event-schemas/schema/m.room.join_rules.yaml
@ -28,6 +28,7 @@ properties:
          - invite
          - private
          - restricted
+          - knock_restricted
        type: string
      allow:
        x-addedInMatrixVersion: "1.2"
--- a/layouts/partials/events/render-event.html
+++ b/layouts/partials/events/render-event.html
@ -25,6 +25,8 @@
   {{ with .title }}{{ . | markdownify }}{{ else }}<code>{{ $event_name }}</code>{{ end }}
  </h1>

+</summary>
+
  <hr/>

 {{ if (index $event_data "x-addedInMatrixVersion") }}
@ -36,8 +38,6 @@

 {{ $event_data.description | markdownify }}

-</summary>
-
 {{ $state_key := index $event_data.properties "state_key" }}

 <table class="basic-info">
--- a/layouts/shortcodes/definition.html
+++ b/layouts/shortcodes/definition.html
@ -39,6 +39,8 @@
 <code>{{ $definition.title }}</code>
 </h1>

+</summary>
+
 <hr/>

 {{ if (index $definition "x-addedInMatrixVersion") }}
@ -47,7 +49,6 @@

 {{ $definition.description | markdownify }}

-</summary>

 {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $definition "name" (printf "\"%s\"" $path)) }}
 {{ $additional_types = uniq $additional_types }}
--- a/layouts/shortcodes/event-fields.html
+++ b/layouts/shortcodes/event-fields.html
@ -26,12 +26,12 @@
 <h1>
 <code>{{ humanize $event.title }}</code>
 </h1>
+</summary>

 <hr/>

 {{ $event.description | markdownify }}

-</summary>

 {{ $event = merge $event (dict "title" "") }}

--- a/meta/releasing.md
+++ b/meta/releasing.md
@ -4,6 +4,51 @@ The whole specification is now released as a single unit/artifact. This document
 the process for releasing the specification and a description of how the (public)
 machinery works.

+## Timeline
+
+The spec is released each calendar quarter. The target release dates are within the
+following ranges:
+
+* Q1: January 20-27 (critically, before FOSDEM).
+* Q2: May 20-27.
+* Q3: August 20-27.
+* Q4: November 1-15 (before recurring November conflicts, like IETF).
+
+The SCT aims to have dates picked out by:
+
+* Q1: January 10.
+* Q2: May 1.
+* Q3: August 1.
+* Q4: October 15.
+
+When a release date is picked, a [checklist](https://github.com/matrix-org/matrix-spec/issues/new?assignees=&labels=release-blocker&projects=&template=release.md&title=Matrix+1.X)
+issue is created to track details of the release. Release blockers should continue to
+be accepted up until 7 calendar days prior to the release date.
+
+**Release dates are not promises.** The SCT reserves the ability to change, cancel,
+postpone, etc a release for any reason. Do not rely on a release happening on a given
+day until the release has actually happened & blog post published.
+
+Once a release is scheduled, the SCT will begin planning what the next release is
+expected to look like. The plan should be included in the spec release blog post,
+and be ready for exeuction on spec release day. Plans are guides and not promises.
+
+A blog post for the SCT members to review should be ready at minimum 1 week before
+the target release date. 1-2 days before the release itself, the prerequisite steps
+below are executed to ensure the spec release can go ahead.
+
+## Release composition
+
+*This section is a work in progress.*
+
+Mentioned above, the SCT aims to have spec releases quarterly. Each quarter has a
+slightly different theme to it:
+
+* Q1: Massive feature release, if possible. This generally happens thanks to FOSDEM.
+* Q2: Regular feature release, if possible.
+* Q3: Momentum-continuing feature release, if possible.
+* Q4: Preferably a maintenance release, but will accept features per normal.
+
 ## Prerequisites / preparation

 First, can we even release the spec? This stage is mostly preparation work needed
--- a/scripts/check-newsfragments
+++ b/scripts/check-newsfragments
@ -21,6 +21,12 @@ matched=0
 while read f; do
    basename=$(basename $f)
    dirname=$(dirname $f)
+    extension="${f##*.}"
+
+    # check that each changelog file has a known extension
+    if ! [[ "$extension" == "new" || "$extension" == "feature" || "$extension" == "clarification" || "$extension" == "breaking" || "$extension" == "deprecation" ]]; then
+        echo -e "\e[31mERROR: newsfragment $f does not have one of the required file extensions for a changelog entry: .new, .feature, .clarification, .breaking, .deprecation\e[39m" >&2
+    fi

    # check that there is nothing that looks like a newsfile outside one of the
    # expected directories.
@ -31,6 +37,7 @@ while read f; do
        # see if this newsfile corresponds to the right PR
        [[ -n "$pr" && "$basename" == "$pr".* ]] && matched=1
    fi
+# find all files in the 'changelogs/*/' dirs that are in the form `<digits>.<text>`
 done < <(find changelogs -regex '.*/[0-9]+\.[^/]+$')

 if [[ -n "$pr" && "$matched" -eq 0 ]]; then
				`@ -1 +0,0 @@`
				`Clarify that the term "Canonical JSON" is a specific thing within the matrix specification.`
				`@ -1 +0,0 @@`
				`Clarifications of event ID formats in early room versions`
				`@ -1 +0,0 @@`
				`Fix various typos throughout the specification.`
				`@ -1 +0,0 @@`
				`Clarify the sections of the specification concerning aggregation of child events.`
				`@ -1 +0,0 @@`
				`Clarify that reply chain fallback for threads may not be present.`
				`@ -1 +0,0 @@`
				Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925).
				`@ -1 +0,0 @@`
				`Clarify what event property the content-specific push rules match against.`
				`@ -1 +0,0 @@`
				`Clarify the semantics that make requests idempotent.`
				`@ -1 +0,0 @@`
				`Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.`
				`@ -1 +0,0 @@`
				`Improve documentation of how clients use push rules.`