Merge branch 'main' into clarify-identifier-localparts

.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 -->

.github/workflows/main.yml

@@ -23,16 +23,9 @@ jobs:
         uses: actions/setup-node@v2
         with:
           node-version: '14'
-      - name: "⚙️ npm"
-        working-directory: "./scripts"
-        run: |
-          npm install
       - name: "🔎 Run validator"
-        working-directory: "./scripts"
         run: |
-          node validator.js -s "../data/api/application-service"
+          npx @redocly/cli@latest lint data/api/*/*.yaml
-          node validator.js -s "../data/api/client-server"
-          node validator.js -s "../data/api/push-gateway"
 
   check-examples:
     name: "🔎 Check Event schema examples"
@@ -93,18 +86,26 @@ jobs:
           pip install -r scripts/requirements.txt
       - name: "📦 Asset creation"
         run: |
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            export RELEASE="${GITHUB_REF/refs\/tags\//}"
+          else
+            export RELEASE="unstable"
+          fi
           # The output path matches the final deployment path at spec.matrix.org
           scripts/dump-swagger.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api application-service \
+            -r "$RELEASE" \
             -o spec/application-service-api/api.json
           scripts/dump-swagger.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api client-server \
+            -r "$RELEASE" \
             -o spec/client-server-api/api.json
           scripts/dump-swagger.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api push-gateway \
+            -r "$RELEASE" \
             -o spec/push-gateway-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
@@ -147,7 +148,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
         with:
-          hugo-version: '0.93.3'
+          hugo-version: '0.113.0'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v2

.gitmodules

@@ -1,4 +1,7 @@
 [submodule "themes/docsy"]
 	path = themes/docsy
+	# We use our own forked version of the Docsy theme,
+	# to avoid loading fonts from CDNs, which Docsy currently
+	# doesn't support (see https://github.com/google/docsy/issues/605).
 	url = https://github.com/matrix-org/docsy.git
 	branch = master

assets/scss/custom.scss

@@ -68,9 +68,8 @@ Custom SCSS for the Matrix spec
     margin-top: 1rem;
   }
 
-  &>.td-sidebar-nav__section > li > a.td-sidebar-link {
+  .td-sidebar-nav__section .ul-1 ul {
-      font-weight: $font-weight-bold;
+    padding-left: 0;
-      font-size: 1.3rem;
   }
 
   /* This is to make the width of the items that have sub-items (like room versions)
@@ -79,12 +78,20 @@ Custom SCSS for the Matrix spec
     padding-right: 0 !important;
   }
 
-  a.indent-1 {
+  .ul-1 > li > a {
     padding-left: 1rem !important;
   }
 
-  a.indent-2 {
+  .ul-2 > li > a {
-    padding-left: 2rem;
+    padding-left: 2rem !important;
+  }
+
+  a.td-sidebar-link.tree-root {
+    color: $gray-800;
+    font-weight: $font-weight-bold;
+    font-size: 1.3rem;
+    margin-bottom: 0;
+    border-bottom: none;
   }
 
   a, a.td-sidebar-link {
@@ -103,7 +110,6 @@ Custom SCSS for the Matrix spec
 
     &.active, &active:hover {
       background-color: $secondary-background;
-      font-weight: $font-weight-normal;
     }
   }
 }
@@ -344,19 +350,37 @@ footer {
   }
 
   table {
-    /* Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
+    @media (max-width: 800px) {
-     * tables with a "display" property of "block".
+      /* Docsy by default applies `overflow-x: auto;` to tables, which
-     *
+       * results in annoying horizontal scrolling on mobile, so we instead
-     * However, for "table-layout: fixed" to be effective, an element must have a
+       * switch to a fixed table layout on a narrow browser width.
-     * "display" property of "table".
+       * (On a wider width the default auto table-layout provides better readability.)
-     *
+       *
-     * Thus, we override the "display" property here. This may no longer be necessary once
+       * Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
-     * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
+       * tables with a "display" property of "block".
-     * For more details, see
+       * However, for "table-layout: fixed" to be effective, an element must have a
-     * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
+       * "display" property of "table".
-    display: table;
+       *
-    table-layout: fixed;
+       * Thus, we override the "display" property here. This may no longer be necessary once
-    width: 100%;
+       * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
+       * For more details, see
+       * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
+      display: table;
+      table-layout: fixed;
+      width: 100%;
+
+      .col-name, .col-type, .col-status {
+        width: 25%;
+      }
+
+      .col-description {
+        width: 50%;
+      }
+
+      .col-status-description {
+        width: 75%;
+      }
+    }
 
     // add some space between two tables when they are right next to each other
     & + table {
@@ -374,7 +398,7 @@ footer {
       padding: 1rem;
     }
 
-    &.object-table, &.response-table {
+    &.object-table, &.response-table, &.content-type-table {
         border: 1px $table-border-color solid;
 
         caption {
@@ -403,19 +427,6 @@ footer {
     &.basic-info th {
       width: 15rem;
     }
-
-    .col-name, .col-type, .col-status {
-      width: 25%;
-    }
-
-    .col-description {
-      width: 50%;
-    }
-
-    .col-status-description {
-      width: 75%;
-    }
-
   }
 
   pre {

changelogs/appendices/newsfragments/1468.clarification

@@ -1 +0,0 @@
-Clarify that the term "Canonical JSON" is a specific thing within the matrix specification.

changelogs/appendices/newsfragments/1483.clarification

@@ -1 +0,0 @@
-Remove references to groups

changelogs/appendices/newsfragments/1484.clarification

@@ -1 +0,0 @@
-Clarifications of event ID formats in early room versions

changelogs/appendices/newsfragments/1573.clarification

@@ -0,0 +1 @@
+Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten

changelogs/appendices/newsfragments/1583.feature

@@ -0,0 +1 @@
+Allow `+` in Matrix IDs, per [MSC4009](https://github.com/matrix-org/matrix-spec-proposals/pull/4009).

changelogs/application_service/newsfragments/1447.clarification

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

changelogs/application_service/newsfragments/1584.clarification

@@ -0,0 +1 @@
+Fix JSON schema of custom fields in query.

changelogs/client_server/newsfragments/1424.clarification

@@ -1 +0,0 @@
-Clarify the sections of the specification concerning aggregation of child events.

changelogs/client_server/newsfragments/1432.clarification

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

changelogs/client_server/newsfragments/1439.clarification

@@ -1 +0,0 @@
-Clarify that reply chain fallback for threads may not be present.

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).

changelogs/client_server/newsfragments/1441.clarification

@@ -1 +0,0 @@
-Clarify what event property the content-specific push rules match against.

changelogs/client_server/newsfragments/1447.clarification

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

changelogs/client_server/newsfragments/1449.clarification

@@ -1 +0,0 @@
-Clarify the semantics that make requests idempotent.

changelogs/client_server/newsfragments/1455.clarification

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

changelogs/client_server/newsfragments/1457.clarification

@@ -1 +0,0 @@
-Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

changelogs/client_server/newsfragments/1461.clarification

@@ -1 +0,0 @@
-Improve documentation of how clients use push rules.

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.

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).

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).

changelogs/client_server/newsfragments/1465.clarifications

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

changelogs/client_server/newsfragments/1474.clarification

@@ -1 +0,0 @@
-Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks.

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).

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.

changelogs/client_server/newsfragments/1485.clarification

@@ -1 +0,0 @@
-Remove fictitious `token` parameter on `/keys/query` endpoint

changelogs/client_server/newsfragments/1487.clarification

@@ -1 +0,0 @@
-Fix rendering of properties with a list of types

changelogs/client_server/newsfragments/1500.clarification

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

changelogs/client_server/newsfragments/1552.clarification

@@ -0,0 +1 @@
+Fix missing `type` property in the JSON schema definition of the `m.reaction` event.  Contributed by @chebureki.

changelogs/client_server/newsfragments/1563.clarification

@@ -0,0 +1 @@
+Make sure examples types match schema in definitions.

changelogs/client_server/newsfragments/1564.clarification

@@ -0,0 +1 @@
+Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas.

changelogs/client_server/newsfragments/1578.clarification

@@ -0,0 +1 @@
+Fix broken header formatting. Contributed by @midnightveil.

changelogs/client_server/newsfragments/1579.clarification

@@ -0,0 +1 @@
+Render binary request and response bodies.

changelogs/client_server/newsfragments/1585.clarification

@@ -0,0 +1 @@
+Remove unnecessary `oneOf`s in JSON schemas.

changelogs/client_server/newsfragments/1590.clarification

@@ -0,0 +1 @@
+Fix description of MAC calculation in SAS verification.

changelogs/client_server/newsfragments/1593.clarification

@@ -0,0 +1 @@
+Update link to SAS emoji definition data.

changelogs/identity_service/newsfragments/1457.clarification

@@ -1 +0,0 @@
-Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

changelogs/identity_service/newsfragments/1563.clarification

@@ -0,0 +1 @@
+Make sure examples types match schema in definitions.

changelogs/internal/newsfragments/1310.feature

@@ -0,0 +1 @@
+Upgrade Swagger data to OpenAPI 3.1.

changelogs/internal/newsfragments/1444.clarification

@@ -1 +0,0 @@
-Update references to Inter font.

changelogs/internal/newsfragments/1446.clarification

@@ -1 +0,0 @@
-Endpoint disclosures now hide everything but the URL.

changelogs/internal/newsfragments/1476.clarification

@@ -1 +0,0 @@
-Minor cleanups to the GitHub Actions workflows

changelogs/internal/newsfragments/1542.clarification

@@ -0,0 +1 @@
+Update the CI to validate the file extension of changelog entries.

changelogs/internal/newsfragments/1549.clarification

@@ -0,0 +1 @@
+Disclosure sections now only display their title when collapsed.

changelogs/internal/newsfragments/1551.clarification

@@ -0,0 +1 @@
+Fix the sidebar in recent versions of Hugo

changelogs/internal/newsfragments/1556.clarification

@@ -0,0 +1 @@
+Bump jsonschema to validate JSON Schemas against Draft 2020-12.

changelogs/internal/newsfragments/1558.clarification

@@ -0,0 +1 @@
+Use Redocly CLI to validate OpenAPI definitions.

changelogs/internal/newsfragments/1561.clarification

@@ -0,0 +1 @@
+Use tag name as the OpenAPI definition version.

changelogs/internal/newsfragments/1562.clarification

@@ -0,0 +1 @@
+Make sure version in x-changedInMatrixVersion is a string.

changelogs/internal/newsfragments/1582.clarification

@@ -0,0 +1 @@
+Clarify usage of ABNF for grammar in the documentation style guide.

changelogs/internal/newsfragments/1591.clarification

@@ -0,0 +1 @@
+Update the version of Hugo used to render the spec to v0.113.0.

changelogs/internal/newsfragments/1598.clarification

@@ -0,0 +1 @@
+Fix rendered changelog with new version of towncrier.

changelogs/internal/newsfragments/1601.clarification

@@ -0,0 +1 @@
+Improve the layout of tables on desktop displays. Contributed by Martin Fischer.

changelogs/pyproject.toml

@@ -1,39 +1,66 @@
 [tool.towncrier]
     version = "unused"
-    filename = "../rendered.md"
+    filename = "rendered.md"
-    issue_format = "[#{issue}](https://github.com/matrix-org/matrix-spec/issues/{issue})"
+    template = "template.md.jinja"
-    title_format = "### {name}"  # Matches rendered spec, even if awkward
-    underlines = "   "  # 3 spaces intentionally to hide RST headings
-
-    # Note: The names below have the <strong> tag built-in so the rendered spec *and* the generated
-    # changelog can benefit from sane headings.
 
     [[tool.towncrier.type]]
         directory = "breaking"
-        name = "<strong>Breaking Changes</strong>"
+        name = "Breaking Changes"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "deprecation"
-        name = "<strong>Deprecations</strong>"
+        name = "Deprecations"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "new"
-        name = "<strong>New Endpoints</strong>"
+        name = "New Endpoints"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "removal"
-        name = "<strong>Removed Endpoints</strong>"
+        name = "Removed Endpoints"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "feature"
-        name = "<strong>Backwards Compatible Changes</strong>"
+        name = "Backwards Compatible Changes"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "clarification"
-        name = "<strong>Spec Clarifications</strong>"
+        name = "Spec Clarifications"
         showcontent = true
+
+    [[tool.towncrier.section]]
+        name = "Client-Server API"
+        path = "client_server"
+
+    [[tool.towncrier.section]]
+        name = "Server-Server API"
+        path = "server_server"
+    
+    [[tool.towncrier.section]]
+        name = "Application Service API"
+        path = "application_service"
+
+    [[tool.towncrier.section]]
+        name = "Identity Service API"
+        path = "identity_service"
+    
+    [[tool.towncrier.section]]
+        name = "Push Gateway API"
+        path = "push_gateway"
+    
+    [[tool.towncrier.section]]
+        name = "Room Versions"
+        path = "room_versions"
+    
+    [[tool.towncrier.section]]
+        name = "Appendices"
+        path = "appendices"
+
+    [[tool.towncrier.section]]
+        name = "Internal Changes/Tooling"
+        path = "internal"

changelogs/room_versions/newsfragments/1484.clarification

@@ -1 +0,0 @@
-Clarifications of event ID formats in early room versions

changelogs/server_server/newsfragments/1431.clarification

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

changelogs/server_server/newsfragments/1447.clarification

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

changelogs/server_server/newsfragments/1454.clarification

@@ -1 +0,0 @@
-Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`.

changelogs/server_server/newsfragments/1457.clarification

@@ -1 +0,0 @@
-Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

changelogs/server_server/newsfragments/1466.clarification

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

changelogs/server_server/newsfragments/1473.clarification

@@ -1 +0,0 @@
-* Remove leftover `{key_id}` from `/_matrix/key/v2/server/`

changelogs/server_server/newsfragments/1521.clarification

@@ -0,0 +1 @@
+Document why `/state_ids` can respond with a 404.

changelogs/server_server/newsfragments/1559.clarification

@@ -0,0 +1 @@
+Fix definition of response of `POST /_matrix/federation/v1/user/keys/claim`.

changelogs/server_server/newsfragments/1560.clarification

@@ -0,0 +1 @@
+Fix level of examples in server keys definition.

changelogs/server_server/newsfragments/1563.clarification

@@ -0,0 +1 @@
+Make sure examples types match schema in definitions.

changelogs/server_server/newsfragments/1564.clarification

@@ -0,0 +1 @@
+Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas.

changelogs/server_server/newsfragments/1578.clarification

@@ -0,0 +1 @@
+Fix broken header formatting. Contributed by @midnightveil.

changelogs/template.md.jinja

@@ -0,0 +1,24 @@
+{% for section_name, section in sections.items() %}
+{% if section_name %}
+
+### {{section_name}}
+{% endif %}
+
+{% if section %}
+{% for category, val in definitions.items() if category in section %}
+**{{ definitions[category]['name'] }}**
+
+{% for content, issues in section[category].items() %}
+- {{ content }} (
+{%- for issue in issues %}
+[{{issue}}](https://github.com/matrix-org/matrix-spec/issues/{{issue|trim('#')}}){% if not loop.last %}, {% endif %}
+{%- endfor %}
+)
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+{% endif %}
+{% endfor %}

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"
+# minor = "7"
-# release_date = "February 14, 2023"
+# release_date = "May 25, 2023"
 
 # User interface configuration
 [params.ui]
@@ -62,6 +62,10 @@ current_version_url = "https://spec.matrix.org/latest"
 footer_about_disable = false
 # Collapse HTTP API and event <details> elements
 rendered_data_collapsed = false
+# Hide the search entry in the sidebar
+sidebar_search_disable = true
+# Only show the current page's ancestors, siblings and direct descendants in the sidebar menu
+sidebar_menu_compact = true
 
 [params.links]
 # End user relevant links. These will show up on left side of footer and in the community page if you have one.

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:                      |

content/appendices.md

@@ -90,7 +90,8 @@ To ensure that all implementations use the same JSON encoding we define
 We define this encoding for a value to be the shortest
 UTF-8 JSON encoding with dictionary keys lexicographically sorted by
 Unicode codepoint. Numbers in the JSON must be integers in the range
-`[-(2**53)+1, (2**53)-1]`.
+`[-(2**53)+1, (2**53)-1]`, represented without exponents or decimal
+places, and negative zero `-0` MUST NOT appear.
 
 We pick UTF-8 as the encoding as it should be available to all platforms
 and JSON received from the network is likely to be already encoded using
@@ -304,6 +305,21 @@ The following canonical JSON should be produced:
 {"a":null}
 ```
 
+Given the following JSON object:
+
+```json
+{
+    "a": -0,
+    "b": 1e10
+}
+```
+
+The following canonical JSON should be produced:
+
+```json
+{"a":0,"b":10000000000}
+```
+
 ### Signing Details
 
 JSON is signed by encoding the JSON object without `signatures` or keys
@@ -524,6 +540,8 @@ be represented with a `domain` component under some conditions - see the
 
 #### User Identifiers
 
+{{% changed-in v="1.8" %}}
+
 Users within Matrix are uniquely identified by their Matrix user ID. The
 user ID is namespaced to the homeserver which allocated the account and
 has the form:
@@ -532,7 +550,7 @@ has the form:
 
 The `localpart` of a user ID is an opaque identifier for that user. It
 MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`,
-`.`, `_`, `=`, `-`, and `/`.
+`.`, `_`, `=`, `-`, `/`, and `+`.
 
 The `domain` of a user ID is the [server name](#server-name) of the
 homeserver which allocated the account.
@@ -546,7 +564,7 @@ The complete grammar for a legal user ID is:
     user_id_localpart = 1*user_id_char
     user_id_char = DIGIT
                  / %x61-7A                   ; a-z
-                 / "-" / "." / "=" / "_" / "/"
+                 / "-" / "." / "=" / "_" / "/" / "+"
 
 {{% boxes/rationale %}}
 A number of factors were considered when defining the allowable

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

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))

content/client-server-api/_index.md

@@ -22,11 +22,12 @@ recommended outside test environments.
 Clients are authenticated using opaque `access_token` strings (see [Client
 Authentication](#client-authentication) for details).
 
-All `POST` and `PUT` endpoints, with the exception of
+All `POST` and `PUT` endpoints, with the exception of [`POST
-[`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload), require the
+/_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT
-client to supply a request body containing a (potentially empty) JSON object.
+/_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid),
-Clients should supply a `Content-Type` header of `application/json` for all requests with JSON bodies,
+require the client to supply a request body containing a (potentially empty)
-but this is not required.
+JSON object.  Clients should supply a `Content-Type` header of
+`application/json` for all requests with JSON bodies, but this is not required.
 
 Similarly, all endpoints require the server to return a JSON object,
 with the exception of 200 responses to
@@ -61,7 +62,7 @@ error message e.g.  `M_FORBIDDEN`. Error codes should have their namespace
 first in ALL CAPS, followed by a single `_`. For example, if there was a custom
 namespace `com.mydomain.here`, and a `FORBIDDEN` code, the error code should
 look like `COM.MYDOMAIN.HERE_FORBIDDEN`. Error codes defined by this
-specification should start `M_`.
+specification should start with `M_`.
 
 Some `errcode`s define additional keys which should be present in the error
 response object, but the keys `error` and `errcode` MUST always be present.
@@ -236,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
+The scope of a transaction ID is for a single [device](../index.html#devices),
-session", where that session is identified by a particular access token.
+and a single HTTP endpoint. In other words: a single device could use the same
-When [refreshing](#refreshing-access-tokens) an access token, the
+transaction ID for a request to [`PUT
-transaction ID's scope is retained. This means that if a client with
+/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
-token `A` uses `TXN1` as their transaction ID, refreshes the token to
+and [`PUT
-`B`, and uses `TXN1` again it'll be assumed to be a duplicate request
+/_matrix/client/v3/sendToDevice/{eventType}/{txnId}`](#put_matrixclientv3sendtodeviceeventtypetxnid),
-and ignored. If the client logs out and back in between the `A` and `B`
+and the two requests would be considered distinct because the two are
-tokens, `TXN1` could be used once for each.
+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
@@ -1162,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" %}}
@@ -2670,4 +2690,3 @@ systems.
 {{< cs-module name="event_annotations" >}}
 {{< cs-module name="threading" >}}
 {{< cs-module name="reference_relations" >}}
-

content/client-server-api/modules/end_to_end_encryption.md

@@ -134,8 +134,7 @@ are offline/unable to upload additional keys, though sessions started using
 fallback keys could be vulnerable to replay attacks.
 {{% /boxes/warning %}}
 
-Devices will be informed, [via
+Devices will be informed, [via `/sync`](#e2e-extensions-to-sync), about the number of
-`/sync`](#a-namee2e-extensions-to-sync-extensions-to-sync), about the number of
 one-time keys remaining that can be claimed, as well as whether the fallback
 keys have been used. The device can thus ensure that, while it is online, there
 is a sufficient supply of one-time keys available, and that the fallback keys
@@ -306,7 +305,7 @@ properties.
 | key       | JWK              | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.       |
 | iv        | string           | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.    |
 | hashes    | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. |
-| v         | string           | **Required.** Version of the encrypted attachments protocol. Must be `v2`.                     |
+| v         | string           | **Required.** Version of the encrypted attachment's protocol. Must be `v2`.                    |
 
 `JWK`
 
@@ -777,33 +776,37 @@ The method used to calculate these MACs depends upon the value of the
 message. All current implementations should use the `hkdf-hmac-sha256.v2` method which is
 defined as follows:
 
-The MAC used is HMAC as defined in [RFC
+1. An HMAC key is generated using HKDF, as defined in [RFC
-5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash
+   5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash
-function. The shared secret is supplied as the input keying material. No salt
+   function. The shared secret is supplied as the input keying material. No salt
-is used, and in the info parameter is the concatenation of:
+   is used, and in the info parameter is the concatenation of:
 
--   The string `MATRIX_KEY_VERIFICATION_MAC`.
+   -   The string `MATRIX_KEY_VERIFICATION_MAC`.
--   The Matrix ID of the user whose key is being MAC-ed.
+   -   The Matrix ID of the user whose key is being MAC-ed.
--   The Device ID of the device sending the MAC.
+   -   The Device ID of the device sending the MAC.
--   The Matrix ID of the other user.
+   -   The Matrix ID of the other user.
--   The Device ID of the device receiving the MAC.
+   -   The Device ID of the device receiving the MAC.
--   The `transaction_id` being used.
+   -   The `transaction_id` being used.
--   The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
+   -   The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
-    item being MAC-ed is the list of key IDs.
+       item being MAC-ed is the list of key IDs.
 
-If a key is being MACed, the MAC is performed on the public key as encoded
+2. A MAC is then generated using HMAC as defined in [RFC
-according to the [key algorithm](#key-algorithms).  For example, for `ed25519`
+   2104](https://tools.ietf.org/html/rfc2104) with the key generated above and
-keys, it is the unpadded base64-encoded key.
+   using SHA-256 as the hash function.
 
-If the key list is being MACed, the list is sorted lexicographically and
+   If a key is being MACed, the MAC is performed on the public key as encoded
-comma-separated with no extra whitespace added, with each key written in the
+   according to the [key algorithm](#key-algorithms).  For example, for `ed25519`
-form `{algorithm}:{keyId}`. For example, the key list could look like:
+   keys, it is the unpadded base64-encoded key.
-`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can
-reconstruct the list from the names in the `mac` property of the
-`m.key.verification.mac` message and ensure that no keys were added or removed.
 
-The MAC values are base64-encoded and sent in a
+   If the key list is being MACed, the list is sorted lexicographically and
-[`m.key.verification.mac`](#mkeyverificationmac) message.
+   comma-separated with no extra whitespace added, with each key written in the
+   form `{algorithm}:{keyId}`. For example, the key list could look like:
+   `ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can
+   reconstruct the list from the names in the `mac` property of the
+   `m.key.verification.mac` message and ensure that no keys were added or removed.
+
+3. The MAC values are base64-encoded and sent in a
+   [`m.key.verification.mac`](#mkeyverificationmac) message.
 
 {{% boxes/note %}}
 The MAC method `hkdf-hmac-sha256` used an incorrect base64 encoding, due to a
@@ -892,7 +895,7 @@ following table to get the corresponding emoji:
 
 {{% boxes/note %}}
 This table is available as JSON at
-<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json>
+<https://github.com/matrix-org/matrix-spec/blob/main/data-definitions/sas-emoji.json>.
 {{% /boxes/note %}}
 
 {{% boxes/rationale %}}
@@ -1699,7 +1702,7 @@ When a client is updating a Megolm session in its store, the client MUST ensure:
 
 {{% http-api spec="client-server" api="keys" %}}
 
-##### <a name="e2e-extensions-to-sync"> Extensions to /sync
+##### Extensions to /sync {#e2e-extensions-to-sync}
 
 This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientv3sync)  response,
 as specified below. The server need only populate this property for an

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

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

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.
+{{% changed-in v="1.7" %}}
-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.
 
-Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is
+This module allows users to "mention" other users and rooms within a room event.
-`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
+This is primarily used as an indicator that the recipient should receive a notification
-`org.matrix.custom.html` and therefore requires a `formatted_body`.
+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
+`m.mentions` is defined as follows:
-`formatted_body` using an anchor, like so:
 
-```json
+{{% definition path="api/client-server/definitions/m.mentions" %}}
-{
+
-    "body": "Hello Alice!",
+Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
-    "msgtype": "m.text",
+[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
-    "format": "org.matrix.custom.html",
+Users should not add their own Matrix ID to the `m.mentions` property as outgoing
-    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
+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,
+Although it is possible to silently mention users, it is recommended to include a
-clients should use the following guidelines when making mentions in
+[Matrix URI](/appendices/#uris) in the HTML body of  an [m.room.message](#mroommessage)
-events to be sent:
+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
+If the current user is mentioned in a message, the client should show that
-defined in this module or by a push rule), 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 %}}

content/client-server-api/modules/push.md

@@ -147,17 +147,6 @@ actions are defined:
 
 :   This causes each matching event to generate a notification.
 
-`dont_notify`
-
-:   This prevents each matching event from generating a notification.
-
-`coalesce`
-
-:   This enables notifications for matching events but activates homeserver
-    specific behaviour to intelligently coalesce multiple events into a
-    single notification. Not all homeservers may support this. Those that do
-    not support it should treat it as the `notify` action.
-
 `set_tweak`
 
 :   Sets an entry in the `tweaks` dictionary key that is sent in the
@@ -195,6 +184,12 @@ they are represented as a dictionary with a key equal to their name and
 other keys as their parameters, e.g.
 `{ "set_tweak": "sound", "value": "default" }`.
 
+{{% boxes/note %}}
+Older versions of the Matrix specification included the `dont_notify` and
+`coalesce` actions. These should both be considered no-ops (ignored, not
+rejected) if received from a client.
+{{% /boxes/note %}}
+
 ##### Conditions
 
 `override` and `underride` rules MAY have a list of 'conditions'. All
@@ -440,9 +435,7 @@ Definition:
     "default": true,
     "enabled": false,
     "conditions": [],
-    "actions": [
+    "actions": []
-        "dont_notify"
-    ]
 }
 ```
 
@@ -464,9 +457,7 @@ Definition:
             "pattern": "m.notice",
         }
     ],
-    "actions": [
+    "actions": []
-        "dont_notify",
-    ]
 }
 ```
 
@@ -526,13 +517,50 @@ Definition:
             "pattern": "m.room.member"
         }
     ],
+    "actions": []
+}
+```
+
+<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": [
-        "dont_notify"
+        "notify",
+        {
+            "set_tweak": "sound",
+            "value": "default"
+        },
+        {
+            "set_tweak": "highlight"
+        }
     ]
 }
 ```
 
-**`.m.rule.contains_display_name`**
+<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.
@@ -562,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
@@ -633,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:
 
@@ -685,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.
@@ -882,14 +954,14 @@ To create a rule that suppresses notifications for the room with ID
 
     curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
     '{
-       "actions" : ["dont_notify"]
+       "actions" : []
      }'
 
 To suppress notifications for the user `@spambot:matrix.org`:
 
     curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
     '{
-       "actions" : ["dont_notify"]
+       "actions" : []
      }'
 
 To always notify for messages that contain the work 'cake' and set a

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:
 

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
+}
+```

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
+and a multi-point conferencing unit). Calls can take place in rooms with
-send call events to rooms with exactly two participants.
+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

content/server-server-api.md

@@ -877,8 +877,7 @@ on the resulting `m.room.member` event.
 If the joining server fails all conditions then a 403 `M_FORBIDDEN` error
 is used by the resident server.
 
-<a name="knocking-rooms">
+## Knocking upon a room {#knocking-rooms}
-## Knocking upon a room
 
 Rooms can permit knocking through the join rules, and if permitted this
 gives users a way to request to join (be invited) to the room. Users who
@@ -1270,7 +1269,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).

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

data/api/application-service/protocols.yaml

@@ -11,25 +11,15 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/thirdparty/protocol/{protocol}":
     get:
-      summary: Retrieve metadata about a specific protocol that the application service supports.
+      summary: Retrieve metadata about a specific protocol that the application
+        service supports.
       description: |-
         This API is called by the homeserver when it wants to present clients
         with specific information about the various third-party networks that
@@ -40,42 +30,53 @@ paths:
       parameters:
         - in: path
           name: protocol
-          type: string
           description: The protocol ID.
           required: true
-          x-example: "irc"
+          example: irc
-      responses:
-        200:
-          description: The protocol was found and metadata returned.
           schema:
-            $ref: definitions/protocol.yaml
+            type: string
-        401:
+      responses:
+        "200":
+          description: The protocol was found and metadata returned.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/protocol.yaml
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-        403:
+                  value: {
-          description: |-
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            The credentials supplied by the homeserver were rejected.
+                  }
-          examples:
+        "403":
-            application/json: {
+          description: The credentials supplied by the homeserver were rejected.
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+          content:
-            }
+            application/json:
-          schema:
+              schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
-        404:
+              examples:
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+                  }
+        "404":
           description: No protocol was found with the given path.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                  }
   "/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third-party user.
@@ -89,102 +90,130 @@ paths:
       parameters:
         - in: path
           name: protocol
-          type: string
           description: The protocol ID.
           required: true
-          x-example: irc
+          example: irc
+          schema:
+            type: string
         - in: query
-          name: fields...
+          name: fields
-          type: string
           description: |-
             One or more custom fields that are passed to the application
             service to help identify the user.
-      responses:
-        200:
-          description: The Matrix User IDs found with the given parameters.
           schema:
-            $ref: definitions/user_batch.yaml
+            type: object
-        401:
+            additionalProperties:
+              type: string
+      responses:
+        "200":
+          description: The Matrix User IDs found with the given parameters.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/user_batch.yaml
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-        403:
+                  value: {
-          description: |-
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            The credentials supplied by the homeserver were rejected.
+                  }
-          examples:
+        "403":
-            application/json: {
+          description: The credentials supplied by the homeserver were rejected.
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+          content:
-            }
+            application/json:
-          schema:
+              schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
-        404:
+              examples:
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+                  }
+        "404":
           description: No users were found with the given parameters.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                  }
   "/thirdparty/location/{protocol}":
     get:
       summary: Retrieve Matrix-side portal rooms leading to a third-party location.
-      description: |-
+      description: Retrieve a list of Matrix portal rooms that lead to the matched
-        Retrieve a list of Matrix portal rooms that lead to the matched third-party location.
+        third-party location.
       operationId: queryLocationByProtocol
       security:
         - homeserverAccessToken: []
       parameters:
         - in: path
           name: protocol
-          type: string
           description: The protocol ID.
           required: true
-          x-example: irc
+          example: irc
+          schema:
+            type: string
         - in: query
-          name: fields...
+          name: fields
-          type: string
           description: |-
             One or more custom fields that are passed to the application
             service to help identify the third-party location.
-      responses:
-        200:
-          description: At least one portal room was found.
           schema:
-            $ref: definitions/location_batch.yaml
+            type: object
-        401:
+            additionalProperties:
+              type: string
+      responses:
+        "200":
+          description: At least one portal room was found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/location_batch.yaml
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-        403:
+                  value: {
-          description: |-
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            The credentials supplied by the homeserver were rejected.
+                  }
-          examples:
+        "403":
-            application/json: {
+          description: The credentials supplied by the homeserver were rejected.
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+          content:
-            }
+            application/json:
-          schema:
+              schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
-        404:
+              examples:
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+                  }
+        "404":
           description: No mappings were found with the given parameters.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-  "/thirdparty/location":
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                  }
+  /thirdparty/location:
     get:
       summary: Reverse-lookup third-party locations given a Matrix room alias.
       description: |-
@@ -196,84 +225,118 @@ paths:
       parameters:
         - in: query
           name: alias
-          type: string
           description: The Matrix room alias to look up.
-      responses:
-        200:
-          description: |-
-            All found third-party locations.
           schema:
-            $ref: definitions/location_batch.yaml
+            type: string
-        401:
+      responses:
+        "200":
+          description: All found third-party locations.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/location_batch.yaml
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-        403:
+                  value: {
-          description: |-
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            The credentials supplied by the homeserver were rejected.
+                  }
-          examples:
+        "403":
-            application/json: {
+          description: The credentials supplied by the homeserver were rejected.
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+          content:
-            }
+            application/json:
-          schema:
+              schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
-        404:
+              examples:
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+                  }
+        "404":
           description: No mappings were found with the given parameters.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-  "/thirdparty/user":
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                  }
+  /thirdparty/user:
     get:
       summary: Reverse-lookup third-party users given a Matrix User ID.
-      description: |-
+      description: Retrieve an array of third-party users from a Matrix User ID.
-        Retrieve an array of third-party users from a Matrix User ID.
       operationId: queryUserByID
       security:
         - homeserverAccessToken: []
       parameters:
-        - in: query 
+        - in: query
           name: userid
-          type: string
           description: The Matrix User ID to look up.
-      responses:
-        200:
-          description: |-
-            An array of third-party users.
           schema:
-            $ref: definitions/user_batch.yaml
+            type: string
-        401:
+      responses:
+        "200":
+          description: An array of third-party users.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/user_batch.yaml
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-        403:
+                  value: {
-          description: |-
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            The credentials supplied by the homeserver were rejected.
+                  }
-          examples:
+        "403":
-            application/json: {
+          description: The credentials supplied by the homeserver were rejected.
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+          content:
-            }
+            application/json:
-          schema:
+              schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
-        404:
+              examples:
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+                  }
+        "404":
           description: No mappings were found with the given parameters.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                  }
+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

data/api/application-service/query_room.yaml

@@ -12,21 +12,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomAlias}":
     get:
@@ -43,48 +32,75 @@ paths:
       parameters:
         - in: path
           name: roomAlias
-          type: string
           description: The room alias being queried.
           required: true
-          x-example: "#magicforest:example.com"
+          example: "#magicforest:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             The application service indicates that this room alias exists. The
             application service MUST have created a room and associated it with
             the queried room alias using the client-server API. Additional
             information about the room such as its name and topic can be set
             before responding.
-          examples:
+          content:
-            application/json: {}
+            application/json:
-          schema:
+              schema:
-            type: object
+                type: object
-        401:
+              examples:
+                response:
+                  value: {}
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-        403:
+                  value: {
-          description: |-
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            The credentials supplied by the homeserver were rejected.
+                  }
-          examples:
+        "403":
-            application/json: {
+          description: The credentials supplied by the homeserver were rejected.
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+          content:
-            }
+            application/json:
-          schema:
+              schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
-        404:
+              examples:
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+                  }
+        "404":
           description: |-
             The application service indicates that this room alias does not exist.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                  }
+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

data/api/application-service/query_user.yaml

@@ -12,21 +12,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/users/{userId}":
     get:
@@ -43,45 +32,72 @@ paths:
       parameters:
         - in: path
           name: userId
-          type: string
           description: The user ID being queried.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             The application service indicates that this user exists. The application
             service MUST create the user using the client-server API.
-          examples:
+          content:
-            application/json: {}
+            application/json:
-          schema:
+              schema:
-            type: object
+                type: object
-        401:
+              examples:
+                response:
+                  value: {}
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
-        403:
+                  value: {
-          description: |-
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            The credentials supplied by the homeserver were rejected.
+                  }
-          examples:
+        "403":
-            application/json: {
+          description: The credentials supplied by the homeserver were rejected.
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+          content:
-            }
+            application/json:
-          schema:
+              schema:
-            $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
-        404:
+              examples:
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+                  }
+        "404":
           description: |-
             The application service indicates that this user does not exist.
             Optional error information can be included in the body of this response.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              schema:
-            }
+                $ref: ../client-server/definitions/errors/error.yaml
-          schema:
+              examples:
-            $ref: ../client-server/definitions/errors/error.yaml
+                response:
+                  value: {
+                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                  }
+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

data/api/application-service/transactions.yaml

@@ -12,19 +12,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/transactions/{txnId}":
     put:
@@ -42,35 +33,59 @@ paths:
       parameters:
         - in: path
           name: txnId
-          type: string
           description: |-
             The transaction ID for this set of events. Homeservers generate
             these IDs and they are used to ensure idempotency of requests.
           required: true
-          x-example: "35"
+          example: "35"
-        - in: body
-          name: body
-          description: Transaction information
           schema:
-            type: object
+            type: string
-            example: {
+      requestBody:
-              "events": [
+        content:
-                {"$ref": "../../event-schemas/examples/m.room.member.yaml"},
+          application/json:
-                {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
+            schema:
-              ]
+              type: object
-            }
+              example: {
-            properties:
+                "events": [
-              events:
+                  {
-                type: array
+                    "$ref": "../../event-schemas/examples/m.room.member.yaml"
-                description: |-
+                  },
-                  A list of events, formatted as per the Client-Server API.
+                  {
-                items:
+                    "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
-                  $ref: "../client-server/definitions/client_event.yaml"
+                  }
-            required: ["events"]
+                ]
+              }
+              properties:
+                events:
+                  type: array
+                  description: A list of events, formatted as per the Client-Server API.
+                  items:
+                    $ref: ../client-server/definitions/client_event.yaml
+              required:
+                - events
+        description: Transaction information
       responses:
-        200:
+        "200":
           description: The transaction was processed successfully.
-          examples:
+          content:
-            application/json: {}
+            application/json:
-          schema:
+              schema:
-            type: object
+                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

data/api/client-server/account-data.yaml

@@ -11,21 +11,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Client Config API"
+  title: Matrix Client-Server Client Config API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/user/{userId}/account_data/{type}":
     put:
@@ -40,71 +29,85 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to set account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
         - in: path
-          type: string
           name: type
           required: true
           description: |-
             The event type of the account data to set. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.config"
+          example: org.example.custom.config
-        - in: body
-          name: content
-          required: true
-          description: |-
-            The content of the account data.
           schema:
-            type: object
+            type: string
-            example: {
+      requestBody:
-              "custom_account_data_key": "custom_config_value"}
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "custom_account_data_key": "custom_config_value"
+              }
+        description: The content of the account data.
+        required: true
       responses:
-        200:
+        "200":
-          description:
+          description: The account data was successfully added.
-            The account data was successfully added.
+          content:
-          examples:
+            application/json:
-            application/json: {}
+              schema:
-          schema:
+                type: object
-            type: object
+              examples:
-        400:
+                response:
+                  value: {}
+        "400":
           description: |-
             The request body is not a JSON object. Errcode: `M_BAD_JSON`
             or `M_NOT_JSON`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_NOT_JSON",
+              schema:
-              "error": "Content must be a JSON object."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
-        403:
+                    "errcode": "M_NOT_JSON",
+                    "error": "Content must be a JSON object."
+                  }
+        "403":
           description: |-
             The access token provided is not authorized to modify this user's account 
             data. Errcode: `M_FORBIDDEN`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN",
+              schema:
-              "error": "Cannot add account data for other users."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
-        405:
+                    "errcode": "M_FORBIDDEN",
-          examples:
+                    "error": "Cannot add account data for other users."
-            application/json: {
+                  }
-              "errcode": "M_BAD_JSON",
+        "405":
-              "error": "Cannot set m.fully_read through this API."
-            }
           description: |-
             This `type` of account data is controlled by the server; it cannot be
             modified by clients. Errcode: `M_BAD_JSON`.
-          schema:
+          content:
-            $ref: "../client-server/definitions/errors/error.yaml"
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_BAD_JSON",
+                    "error": "Cannot set m.fully_read through this API."
+                  }
       tags:
         - User data
     get:
@@ -117,51 +120,61 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to get account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
         - in: path
-          type: string
           name: type
           required: true
           description: |-
             The event type of the account data to get. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.config"
+          example: org.example.custom.config
-      responses:
-        200:
-          description:
-            The account data content for the given type.
           schema:
-            type: object
+            type: string
-            example: {
+      responses:
-              "custom_account_data_key": "custom_config_value"}
+        "200":
-        403:
+          description: The account data content for the given type.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  "custom_account_data_key": "custom_config_value"
+                }
+        "403":
           description: |-
             The access token provided is not authorized to retrieve this user's account 
             data. Errcode: `M_FORBIDDEN`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN",
+              schema:
-              "error": "Cannot add account data for other users."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
-        404:
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot add account data for other users."
+                  }
+        "404":
           description: |-
             No account data has been provided for this user with the given `type`.
             Errcode: `M_NOT_FOUND`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_NOT_FOUND",
+              schema:
-              "error": "Account data not found."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Account data not found."
+                  }
       tags:
         - User data
   "/user/{userId}/rooms/{roomId}/account_data/{type}":
@@ -176,79 +189,93 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to set account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
         - in: path
-          type: string
           name: roomId
           required: true
-          description: |-
+          description: The ID of the room to set account data on.
-            The ID of the room to set account data on.
+          example: "!726s6s6q:example.com"
-          x-example: "!726s6s6q:example.com"
+          schema:
+            type: string
         - in: path
-          type: string
           name: type
           required: true
           description: |-
             The event type of the account data to set. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.room.config"
+          example: org.example.custom.room.config
-        - in: body
-          name: content
-          required: true
-          description: |-
-            The content of the account data.
           schema:
-            type: object
+            type: string
-            example: {
+      requestBody:
-              "custom_account_data_key": "custom_account_data_value"}
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "custom_account_data_key": "custom_account_data_value"
+              }
+        description: The content of the account data.
+        required: true
       responses:
-        200:
+        "200":
-          description:
+          description: The account data was successfully added.
-            The account data was successfully added.
+          content:
-          examples:
+            application/json:
-            application/json: {}
+              schema:
-          schema:
+                type: object
-            type: object
+              examples:
-        400:
+                response:
+                  value: {}
+        "400":
           description: |-
             The request body is not a JSON object (errcode `M_BAD_JSON` or
             `M_NOT_JSON`), or the given `roomID` is not a valid room ID
             (errcode `M_INVALID_PARAM`).
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_NOT_JSON",
+              schema:
-              "error": "Content must be a JSON object."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
-        403:
+                    "errcode": "M_NOT_JSON",
+                    "error": "Content must be a JSON object."
+                  }
+        "403":
           description: |-
             The access token provided is not authorized to modify this user's account 
             data. Errcode: `M_FORBIDDEN`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN",
+              schema:
-              "error": "Cannot add account data for other users."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
-        405:
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot add account data for other users."
+                  }
+        "405":
           description: |-
             This `type` of account data is controlled by the server; it cannot be
             modified by clients. Errcode: `M_BAD_JSON`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_BAD_JSON",
+              schema:
-              "error": "Cannot set m.fully_read through this API."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
+                    "errcode": "M_BAD_JSON",
+                    "error": "Cannot set m.fully_read through this API."
+                  }
       tags:
         - User data
     get:
@@ -261,65 +288,95 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to get account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
         - in: path
-          type: string
           name: roomId
           required: true
-          description: |-
+          description: The ID of the room to get account data for.
-            The ID of the room to get account data for.
+          example: "!726s6s6q:example.com"
-          x-example: "!726s6s6q:example.com"
+          schema:
+            type: string
         - in: path
-          type: string
           name: type
           required: true
           description: |-
             The event type of the account data to get. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.room.config"
+          example: org.example.custom.room.config
-      responses:
-        200:
-          description:
-            The account data content for the given type.
           schema:
-            type: object
+            type: string
-            example: {
+      responses:
-              "custom_account_data_key": "custom_config_value"}
+        "200":
-        400:
+          description: The account data content for the given type.
-          description: |-
+          content:
-            The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`.
+            application/json:
-          examples:
+              schema:
-            application/json: {
+                type: object
-              "errcode": "M_INVALID_PARAM",
+                example: {
-              "error": "@notaroomid:example.org is not a valid room ID."
+                  "custom_account_data_key": "custom_config_value"
-            }
+                }
-        403:
+        "400":
+          description: "The given `roomID` is not a valid room ID. Errcode:
+            `M_INVALID_PARAM`."
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "@notaroomid:example.org is not a valid room ID."
+                  }
+        "403":
           description: |-
             The access token provided is not authorized to retrieve this user's account 
             data. Errcode: `M_FORBIDDEN`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN",
+              schema:
-              "error": "Cannot add account data for other users."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
-        404:
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot add account data for other users."
+                  }
+        "404":
           description: |-
             No account data has been provided for this user and this room with the 
             given `type`. Errcode: `M_NOT_FOUND`.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_NOT_FOUND",
+              schema:
-              "error": "Room account data not found."
+                $ref: ../client-server/definitions/errors/error.yaml
-            }
+              examples:
-          schema:
+                response:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room account data not found."
+                  }
       tags:
         - User data
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/admin.yaml

@@ -11,21 +11,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Administration API"
+  title: Matrix Client-Server Administration API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/admin/whois/{userId}":
     get:
@@ -41,75 +30,94 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user to look up.
           required: true
-          x-example: "@peter:rabbit.rocks"
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The lookup was successful.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "user_id": "@peter:rabbit.rocks",
+              schema:
-                "devices": {
+                type: object
-                  "teapot": {
+                properties:
-                    "sessions": [
+                  user_id:
-                      {
+                    type: string
-                        "connections": [
+                    description: The Matrix user ID of the user.
+                  devices:
+                    type: object
+                    description: Each key is an identifier for one of the user's devices.
+                    additionalProperties:
+                      type: object
+                      title: DeviceInfo
+                      properties:
+                        sessions:
+                          type: array
+                          description: A user's sessions (i.e. what they did with an access token from one
+                            login).
+                          items:
+                            type: object
+                            title: SessionInfo
+                            properties:
+                              connections:
+                                type: array
+                                description: Information particular connections in the session.
+                                items:
+                                  type: object
+                                  title: ConnectionInfo
+                                  properties:
+                                    ip:
+                                      type: string
+                                      description: Most recently seen IP address of the session.
+                                    last_seen:
+                                      type: integer
+                                      format: int64
+                                      description: Unix timestamp that the session was last active.
+                                    user_agent:
+                                      type: string
+                                      description: User agent string last seen in the session.
+              examples:
+                response:
+                  value: {
+                    "user_id": "@peter:rabbit.rocks",
+                    "devices": {
+                      "teapot": {
+                        "sessions": [
                           {
-                            "ip": "127.0.0.1",
+                            "connections": [
-                            "last_seen": 1411996332123,
+                              {
-                            "user_agent": "curl/7.31.0-DEV"
+                                "ip": "127.0.0.1",
-                          },
+                                "last_seen": 1411996332123,
-                          {
+                                "user_agent": "curl/7.31.0-DEV"
-                            "ip": "10.0.0.2",
+                              },
-                            "last_seen": 1411996332123,
+                              {
-                            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
+                                "ip": "10.0.0.2",
+                                "last_seen": 1411996332123,
+                                "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
+                              }
+                            ]
                           }
                         ]
                       }
-                    ]
+                    }
                   }
-                }
-              }
-          schema:
-            type: object
-            properties:
-              user_id:
-                type: string
-                description: The Matrix user ID of the user.
-              devices:
-                type: object
-                description: |-
-                  Each key is an identifier for one of the user's devices.
-                additionalProperties:
-                  type: object
-                  title: DeviceInfo
-                  properties:
-                    sessions:
-                      type: array
-                      description: A user's sessions (i.e. what they did with an access token from one login).
-                      items:
-                        type: object
-                        title: SessionInfo
-                        properties:
-                          connections:
-                            type: array
-                            description: Information particular connections in the session.
-                            items:
-                              type: object
-                              title: ConnectionInfo
-                              properties:
-                                ip:
-                                  type: string
-                                  description: Most recently seen IP address of the session.
-                                last_seen:
-                                  type: integer
-                                  format: int64
-                                  description: Unix timestamp that the session was last active.
-                                user_agent:
-                                  type: string
-                                  description: User agent string last seen in the session.
       tags:
         - Server administration
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/administrative_contact.yaml

@@ -12,23 +12,12 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Account Administrative Contact API"
+  title: Matrix Client-Server Account Administrative Contact API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/account/3pid":
+  /account/3pid:
     get:
       summary: Gets a list of a user's third-party identifiers.
       description: |-
@@ -44,48 +33,56 @@ paths:
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The lookup was successful.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "threepids": [
+              schema:
-                {
+                type: object
-                  "medium": "email",
+                properties:
-                  "address": "monkey@banana.island",
+                  threepids:
-                  "validated_at": 1535176800000,
+                    type: array
-                  "added_at": 1535336848756
+                    items:
-                }
+                      type: object
-              ]
+                      title: Third-party identifier
-            }
+                      properties:
-          schema:
+                        medium:
-            type: object
+                          type: string
-            properties:
+                          description: The medium of the third-party identifier.
-              threepids:
+                          enum:
-                type: array
+                            - email
-                items:
+                            - msisdn
-                  type: object
+                        address:
-                  title: Third-party identifier
+                          type: string
-                  properties:
+                          description: The third-party identifier address.
-                    medium:
+                        validated_at:
-                      type: string
+                          type: integer
-                      description: The medium of the third-party identifier.
+                          format: int64
-                      enum: ["email", "msisdn"]
+                          description: |-
-                    address:
+                            The timestamp, in milliseconds, when the identifier was
-                      type: string
+                            validated by the identity server.
-                      description: The third-party identifier address.
+                        added_at:
-                    validated_at:
+                          type: integer
-                      type: integer
+                          format: int64
-                      format: int64
+                          description: The timestamp, in milliseconds, when the homeserver associated the
-                      description: |-
+                            third-party identifier with the user.
-                        The timestamp, in milliseconds, when the identifier was
+                      required:
-                        validated by the identity server.
+                        - medium
-                    added_at:
+                        - address
-                      type: integer
+                        - validated_at
-                      format: int64
+                        - added_at
-                      description:
+              examples:
-                        The timestamp, in milliseconds, when the homeserver
+                response:
-                        associated the third-party identifier with the user.
+                  value: {
-                  required: ['medium', 'address', 'validated_at', 'added_at']
+                    "threepids": [
+                      {
+                        "medium": "email",
+                        "address": "monkey@banana.island",
+                        "validated_at": 1535176800000,
+                        "added_at": 1535336848756
+                      }
+                    ]
+                  }
       tags:
         - Account management
     post:
@@ -105,36 +102,40 @@ paths:
       deprecated: true
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
+            schema:
-          schema:
+              type: object
-            type: object
+              properties:
-            properties:
+                three_pid_creds:
-              three_pid_creds:
+                  title: ThreePidCredentials
-                title: "ThreePidCredentials"
+                  type: object
-                type: object
+                  description: The third-party credentials to associate with the account.
-                description: The third-party credentials to associate with the account.
+                  properties:
-                properties:
+                    client_secret:
-                  client_secret:
+                      type: string
-                    type: string
+                      description: The client secret used in the session with the identity server.
-                    description: The client secret used in the session with the identity server.
+                    id_server:
-                  id_server:
+                      type: string
-                    type: string
+                      description: The identity server to use.
-                    description: The identity server to use.
+                    id_access_token:
-                  id_access_token:
+                      type: string
-                    type: string
+                      description: |-
-                    description: |-
+                        An access token previously registered with the identity server. Servers
-                      An access token previously registered with the identity server. Servers
+                        can treat this as optional to distinguish between r0.5-compatible clients
-                      can treat this as optional to distinguish between r0.5-compatible clients
+                        and this specification version.
-                      and this specification version.
+                    sid:
-                  sid:
+                      type: string
-                    type: string
+                      description: The session identifier given by the identity server.
-                    description: The session identifier given by the identity server.
+                  required:
-                required: ["client_secret", "id_server", "id_access_token", "sid"]
+                    - client_secret
-            required: ["three_pid_creds"]
+                    - id_server
-            example: {
+                    - id_access_token
+                    - sid
+              required:
+                - three_pid_creds
+              example: {
                 "three_pid_creds": {
                   "id_server": "matrix.org",
                   "id_access_token": "abc123_OpaqueString",
@@ -142,45 +143,52 @@ paths:
                   "client_secret": "d0nt-T3ll"
                 }
               }
+        required: true
       responses:
-        200:
+        "200":
           description: The addition was successful.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "submit_url": "https://example.org/path/to/submitToken"
+              schema:
-            }
+                type: object
-          schema:
+                properties:
-            type: object
+                  submit_url:
-            properties:
+                    type: string
-              submit_url:
+                    format: uri
-                type: string
+                    description: |-
-                format: uri
+                      An optional field containing a URL where the client must
-                description: |-
+                      submit the validation token to, with identical parameters
-                  An optional field containing a URL where the client must
+                      to the Identity Service API's `POST
-                  submit the validation token to, with identical parameters
+                      /validate/email/submitToken` endpoint (without the requirement
-                  to the Identity Service API's `POST
+                      for an access token). The homeserver must send this token to the
-                  /validate/email/submitToken` endpoint (without the requirement
+                      user (if applicable), who should then be prompted to provide it
-                  for an access token). The homeserver must send this token to the
+                      to the client.
-                  user (if applicable), who should then be prompted to provide it
-                  to the client.
 
-                  If this field is not present, the client can assume that
+                      If this field is not present, the client can assume that
-                  verification will happen without the client's involvement
+                      verification will happen without the client's involvement
-                  provided the homeserver advertises this specification version
+                      provided the homeserver advertises this specification version
-                  in the `/versions` response (ie: r0.5.0).
+                      in the `/versions` response (ie: r0.5.0).
-                example: "https://example.org/path/to/submitToken"
+                    example: https://example.org/path/to/submitToken
-        403:
+              examples:
+                response:
+                  value: {
+                    "submit_url": "https://example.org/path/to/submitToken"
+                  }
+        "403":
           description: The credentials could not be verified with the identity server.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "errcode": "M_THREEPID_AUTH_FAILED",
+              schema:
-                "error": "The third-party credentials could not be verified by the identity server."
+                $ref: definitions/errors/error.yaml
-              }
+              examples:
-          schema:
+                response:
-            "$ref": "definitions/errors/error.yaml"
+                  value: {
+                    "errcode": "M_THREEPID_AUTH_FAILED",
+                    "error": "The third-party credentials could not be verified by the identity server."
+                  }
       tags:
         - Account management
-  "/account/3pid/add":
+  /account/3pid/add:
     post:
       summary: Adds contact information to the user's account.
       description: |-
@@ -194,47 +202,55 @@ paths:
       operationId: add3PID
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
+            schema:
-          schema:
+              type: object
-            type: object
+              properties:
-            properties:
+                auth:
-              auth:
+                  description: |-
-                description: |-
+                    Additional authentication information for the
-                  Additional authentication information for the
+                    user-interactive authentication API.
-                  user-interactive authentication API.
+                  allOf:
-                allOf:
+                    - $ref: definitions/auth_data.yaml
-                - $ref: "definitions/auth_data.yaml"
+                client_secret:
-              client_secret:
+                  type: string
-                type: string
+                  description: The client secret used in the session with the homeserver.
-                description: The client secret used in the session with the homeserver.
+                  example: d0nt-T3ll
-                example: "d0nt-T3ll"
+                sid:
-              sid:
+                  type: string
-                type: string
+                  description: The session identifier given by the homeserver.
-                description: The session identifier given by the homeserver.
+                  example: abc123987
-                example: "abc123987"
+              required:
-            required: ["client_secret",  "sid"]
+                - client_secret
+                - sid
+        required: true
       responses:
-        200:
+        "200":
           description: The addition was successful.
-          examples:
+          content:
-            application/json: {}
+            application/json:
-          schema:
+              schema:
-            type: object
+                type: object
-        401:
+              examples:
-          description: |-
+                response:
-            The homeserver requires additional authentication information.
+                  value: {}
-          schema:
+        "401":
-            "$ref": "definitions/auth_response.yaml"
+          description: The homeserver requires additional authentication information.
-        429:
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
           description: This request was rate-limited.
-          schema:
+          content:
-            "$ref": "definitions/errors/rate_limited.yaml"
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
-  "/account/3pid/bind":
+  /account/3pid/bind:
     post:
       summary: Binds a 3PID to the user's account through an Identity Service.
       description: |-
@@ -248,47 +264,55 @@ paths:
       operationId: bind3PID
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
+            schema:
-          schema:
+              type: object
-            type: object
+              properties:
-            properties:
+                client_secret:
-              client_secret:
+                  type: string
-                type: string
+                  description: The client secret used in the session with the identity server.
-                description: The client secret used in the session with the identity server.
+                id_server:
-              id_server:
+                  type: string
-                type: string
+                  description: The identity server to use.
-                description: The identity server to use.
+                id_access_token:
-              id_access_token:
+                  type: string
-                type: string
+                  description: An access token previously registered with the identity server.
-                description: |-
+                sid:
-                  An access token previously registered with the identity server.
+                  type: string
-              sid:
+                  description: The session identifier given by the identity server.
-                type: string
+              required:
-                description: The session identifier given by the identity server.
+                - client_secret
-            required: ["client_secret", "id_server", "id_access_token", "sid"]
+                - id_server
-            example: {
+                - id_access_token
-              "id_server": "example.org",
+                - sid
-              "id_access_token": "abc123_OpaqueString",
+              example: {
-              "sid": "abc123987",
+                "id_server": "example.org",
-              "client_secret": "d0nt-T3ll"
+                "id_access_token": "abc123_OpaqueString",
-            }
+                "sid": "abc123987",
+                "client_secret": "d0nt-T3ll"
+              }
+        required: true
       responses:
-        200:
+        "200":
           description: The addition was successful.
-          examples:
+          content:
-            application/json: {}
+            application/json:
-          schema:
+              schema:
-            type: object
+                type: object
-        429:
+              examples:
+                response:
+                  value: {}
+        "429":
           description: This request was rate-limited.
-          schema:
+          content:
-            "$ref": "definitions/errors/rate_limited.yaml"
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
-  "/account/3pid/delete":
+  /account/3pid/delete:
     post:
       summary: Deletes a third-party identifier from the user's account
       description: |-
@@ -301,59 +325,63 @@ paths:
       operationId: delete3pidFromAccount
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
+            schema:
-          schema:
+              type: object
-            type: object
+              properties:
-            properties:
+                id_server:
-              id_server:
+                  type: string
-                type: string
+                  description: |-
-                description: |-
                     The identity server to unbind from. If not provided, the homeserver
                     MUST use the `id_server` the identifier was added through. If the
                     homeserver does not know the original `id_server`, it MUST return
                     a `id_server_unbind_result` of `no-support`.
-                example: "example.org"
+                  example: example.org
-              medium:
+                medium:
-                type: string
+                  type: string
-                description: The medium of the third-party identifier being removed.
+                  description: The medium of the third-party identifier being removed.
-                enum: ["email", "msisdn"]
+                  enum:
-                example: "email"
+                    - email
-              address:
+                    - msisdn
-                type: string
+                  example: email
-                description: The third-party address being removed.
+                address:
-                example: "example@example.org"
+                  type: string
-            required: ['medium', 'address']
+                  description: The third-party address being removed.
+                  example: example@example.org
+              required:
+                - medium
+                - address
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The homeserver has disassociated the third-party identifier from the
             user.
-          schema:
+          content:
-            type: object
+            application/json:
-            properties:
+              schema:
-              id_server_unbind_result:
+                type: object
-                type: string
+                properties:
-                enum:
+                  id_server_unbind_result:
-                  # XXX: I don't know why, but the order matters here so that "no-support"
+                    type: string
-                  # doesn't become "no- support" by the renderer.
+                    enum:
-                  - "no-support"
+                      - no-support
-                  - "success"
+                      - success
-                description: |-
+                    description: |-
-                  An indicator as to whether or not the homeserver was able to unbind
+                      An indicator as to whether or not the homeserver was able to unbind
-                  the 3PID from the identity server. `success` indicates that the
+                      the 3PID from the identity server. `success` indicates that the
-                  identity server has unbound the identifier whereas `no-support`
+                      identity server has unbound the identifier whereas `no-support`
-                  indicates that the identity server refuses to support the request
+                      indicates that the identity server refuses to support the request
-                  or the homeserver was not able to determine an identity server to
+                      or the homeserver was not able to determine an identity server to
-                  unbind from.
+                      unbind from.
-                example: "success"
+                    example: success
-            required:
+                required:
-              - id_server_unbind_result
+                  - id_server_unbind_result
       tags:
         - Account management
-  "/account/3pid/unbind":
+  /account/3pid/unbind:
     post:
       summary: Removes a user's third-party identifier from an identity server.
       description: |-
@@ -366,60 +394,65 @@ paths:
       operationId: unbind3pidFromAccount
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
+            schema:
-          schema:
+              type: object
-            type: object
+              properties:
-            properties:
+                id_server:
-              id_server:
+                  type: string
-                type: string
+                  description: |-
-                description: |-
                     The identity server to unbind from. If not provided, the homeserver
                     MUST use the `id_server` the identifier was added through. If the
                     homeserver does not know the original `id_server`, it MUST return
                     a `id_server_unbind_result` of `no-support`.
-                example: "example.org"
+                  example: example.org
-              medium:
+                medium:
-                type: string
+                  type: string
-                description: The medium of the third-party identifier being removed.
+                  description: The medium of the third-party identifier being removed.
-                enum: ["email", "msisdn"]
+                  enum:
-                example: "email"
+                    - email
-              address:
+                    - msisdn
-                type: string
+                  example: email
-                description: The third-party address being removed.
+                address:
-                example: "example@example.org"
+                  type: string
-            required: ['medium', 'address']
+                  description: The third-party address being removed.
+                  example: example@example.org
+              required:
+                - medium
+                - address
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The identity server has disassociated the third-party identifier from the
             user.
-          schema:
+          content:
-            type: object
+            application/json:
-            properties:
+              schema:
-              id_server_unbind_result:
+                type: object
-                type: string
+                properties:
-                enum:
+                  id_server_unbind_result:
-                  # XXX: I don't know why, but the order matters here so that "no-support"
+                    type: string
-                  # doesn't become "no- support" by the renderer.
+                    enum:
-                  - "no-support"
+                      - no-support
-                  - "success"
+                      - success
-                description: |-
+                    description: |-
-                  An indicator as to whether or not the identity server was able to unbind
+                      An indicator as to whether or not the identity server was able to unbind
-                  the 3PID. `success` indicates that the identity server has unbound the
+                      the 3PID. `success` indicates that the identity server has unbound the
-                  identifier whereas `no-support` indicates that the identity server
+                      identifier whereas `no-support` indicates that the identity server
-                  refuses to support the request or the homeserver was not able to determine
+                      refuses to support the request or the homeserver was not able to determine
-                  an identity server to unbind from.
+                      an identity server to unbind from.
-                example: "success"
+                    example: success
-            required:
+                required:
-              - id_server_unbind_result
+                  - id_server_unbind_result
       tags:
         - Account management
-  "/account/3pid/email/requestToken":
+  /account/3pid/email/requestToken:
     post:
-      summary: Begins the validation process for an email address for association with the user's account.
+      summary: Begins the validation process for an email address for association with
+        the user's account.
       description: |-
         The homeserver must check that the given email address is **not**
         already associated with an account on this homeserver. This API should
@@ -430,49 +463,58 @@ paths:
         the email itself, either by sending a validation email itself or by using
         a service it has control over.
       operationId: requestTokenTo3PIDEmail
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
+            schema:
-          schema:
+              $ref: definitions/request_email_validation.yaml
-            $ref: "definitions/request_email_validation.yaml"
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             An email was sent to the given address. Note that this may be an
             email containing the validation token or it may be informing the
             user of an error.
-          schema:
+          content:
-            $ref: "definitions/request_token_response.yaml"
+            application/json:
-        403:
+              schema:
-          description: |-
+                $ref: definitions/request_token_response.yaml
-            The homeserver does not allow the third-party identifier as a
+        "400":
-            contact option.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             The third-party identifier is already in use on the homeserver, or
             the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
             can be returned if the server does not trust/support the identity server
             provided in the request.
-          schema:
+          content:
-            $ref: "definitions/errors/error.yaml"
+            application/json:
-          examples:
+              schema:
-            application/json: {
+                $ref: definitions/errors/error.yaml
-              "errcode": "M_THREEPID_IN_USE",
+              examples:
-              "error": "Third-party identifier already in use"
+                response:
-            }
+                  value: {
+                    "errcode": "M_THREEPID_IN_USE",
+                    "error": "Third-party identifier already in use"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
-  "/account/3pid/msisdn/requestToken":
+  /account/3pid/msisdn/requestToken:
     post:
-      summary: Begins the validation process for a phone number for association with the user's account.
+      summary: Begins the validation process for a phone number for association with
+        the user's account.
       description: |-
         The homeserver must check that the given phone number is **not**
         already associated with an account on this homeserver. This API should
@@ -483,40 +525,63 @@ paths:
         the phone number itself, either by sending a validation message itself or by using
         a service it has control over.
       operationId: requestTokenTo3PIDMSISDN
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
+            schema:
-          schema:
+              $ref: definitions/request_msisdn_validation.yaml
-            $ref: "definitions/request_msisdn_validation.yaml"
+        required: true
       responses:
-        200:
+        "200":
           description: An SMS message was sent to the given phone number.
-          schema:
+          content:
-            $ref: "definitions/request_token_response.yaml"
+            application/json:
-        403:
+              schema:
-          description: |-
+                $ref: definitions/request_token_response.yaml
-            The homeserver does not allow the third-party identifier as a
+        "400":
-            contact option.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             The third-party identifier is already in use on the homeserver, or
             the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
             can be returned if the server does not trust/support the identity server
             provided in the request.
-          schema:
+          content:
-            $ref: "definitions/errors/error.yaml"
+            application/json:
-          examples:
+              schema:
-            application/json: {
+                $ref: definitions/errors/error.yaml
-              "errcode": "M_THREEPID_IN_USE",
+              examples:
-              "error": "Third-party identifier already in use"
+                response:
-            }
+                  value: {
+                    "errcode": "M_THREEPID_IN_USE",
+                    "error": "Third-party identifier already in use"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

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

data/api/client-server/appservice_room_directory.yaml

@@ -11,28 +11,14 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Application Service Room Directory API"
+  title: Matrix Client-Server Application Service Room Directory API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  # Note: this is the same access_token definition used elsewhere in the client
-  # server API, however this expects an access token for an application service.
-  $ref: definitions/security.yaml
 paths:
   "/directory/list/appservice/{networkId}/{roomId}":
     put:
-      summary: |-
+      summary: Updates a room's visibility in the application service's room directory.
-        Updates a room's visibility in the application service's room directory.
       description: |-
         Updates the visibility of a given room on the application service's room
         directory.
@@ -46,43 +32,69 @@ paths:
       operationId: updateAppserviceRoomDirectoryVisibility
       parameters:
         - in: path
-          type: string
           name: networkId
           description: |-
             The protocol (network) ID to update the room list for. This would
             have been provided by the application service as being listed as
             a supported protocol.
           required: true
-          x-example: "irc"
+          example: irc
+          schema:
+            type: string
         - in: path
-          type: string
           name: roomId
           description: The room ID to add to the directory.
           required: true
-          x-example: "!somewhere:example.org"
+          example: "!somewhere:example.org"
-        - in: body
-          name: body
-          required: true
           schema:
-            type: object
+            type: string
-            properties:
+      requestBody:
-              visibility:
+        content:
-                type: string
+          application/json:
-                enum: ["public", "private"]
+            schema:
-                description: |-
+              type: object
-                  Whether the room should be visible (public) in the directory
+              properties:
-                  or not (private).
+                visibility:
-                example: "public"
+                  type: string
-            required: ['visibility']
+                  enum:
+                    - public
+                    - private
+                  description: |-
+                    Whether the room should be visible (public) in the directory
+                    or not (private).
+                  example: public
+              required:
+                - visibility
+        required: true
       security:
         # again, this is the appservice's token - not a typical client's
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The room's directory visibility has been updated.
-          schema:
+          content:
-            type: object
+            application/json:
-          examples:
+              schema:
-            application/json: {}
+                type: object
+              examples:
+                response:
+                  value: {}
       tags:
         - Application service room directory management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+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

data/api/client-server/banning.yaml

@@ -11,21 +11,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Room Banning API"
+  title: Matrix Client-Server Room Banning API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/ban":
     post:
@@ -41,51 +30,60 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room identifier (not alias) from which the user should be banned.
           required: true
-          x-example: "!e42d8c:matrix.org"
+          example: "!e42d8c:matrix.org"
-        - in: body
-          name: body
-          required: true
           schema:
-            type: object
+            type: string
-            example: {
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
                 "reason": "Telling unfunny jokes",
                 "user_id": "@cheeky_monkey:matrix.org"
               }
-            properties:
+              properties:
-              user_id:
+                user_id:
-                type: string
+                  type: string
-                description: The fully qualified user ID of the user being banned.
+                  description: The fully qualified user ID of the user being banned.
-              reason:
+                reason:
-                x-addedInMatrixVersion: "1.1"
+                  x-addedInMatrixVersion: "1.1"
-                type: string
+                  type: string
-                description: The reason the user has been banned. This will be supplied as the
+                  description: The reason the user has been banned. This will be supplied as the
-                  `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
+                    `reason` on the target's updated
-            required: ["user_id"]
+                    [`m.room.member`](/client-server-api/#mroommember) event.
+              required:
+                - user_id
+        required: true
       responses:
-        200:
+        "200":
           description: The user has been kicked and banned from the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
+              schema:
-          schema:
+                type: object
-            type: object
+              examples:
-        403:
+                response:
+                  value: {}
+        "403":
           description: |-
             You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
 
             - The banner is not currently in the room.
             - The banner's power level is insufficient to ban users from the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "errcode": "M_FORBIDDEN",
+              schema:
-                "error": "You do not have a high enough power level to ban from this room."
+                $ref: definitions/errors/error.yaml
-              }
+              examples:
-          schema:
+                response:
-            "$ref": "definitions/errors/error.yaml"
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You do not have a high enough power level to ban from this room."
+                  }
       tags:
         - Room membership
   "/rooms/{roomId}/unban":
@@ -101,50 +99,74 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
-          description: The room identifier (not alias) from which the user should be unbanned.
+          description: The room identifier (not alias) from which the user should be
-          required: true
+            unbanned.
-          x-example: "!e42d8c:matrix.org"
-        - in: body
-          name: body
           required: true
+          example: "!e42d8c:matrix.org"
           schema:
-            type: object
+            type: string
-            example: {
+      requestBody:
-              "user_id": "@cheeky_monkey:matrix.org",
+        content:
-              "reason": "They've been banned long enough"
+          application/json:
-            }
+            schema:
-            properties:
+              type: object
-              user_id:
+              example: {
-                type: string
+                "user_id": "@cheeky_monkey:matrix.org",
-                description: The fully qualified user ID of the user being unbanned.
+                "reason": "They've been banned long enough"
-              reason:
-                x-addedInMatrixVersion: "1.1"
-                type: string
-                description: |-
-                  Optional reason to be included as the `reason` on the subsequent
-                  membership event.
-            required: ["user_id"]
-      responses:
-        200:
-          description: The user has been unbanned from the room.
-          examples:
-            application/json: {
               }
-          schema:
+              properties:
-            type: object
+                user_id:
-        403:
+                  type: string
+                  description: The fully qualified user ID of the user being unbanned.
+                reason:
+                  x-addedInMatrixVersion: "1.1"
+                  type: string
+                  description: |-
+                    Optional reason to be included as the `reason` on the subsequent
+                    membership event.
+              required:
+                - user_id
+        required: true
+      responses:
+        "200":
+          description: The user has been unbanned from the room.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "403":
           description: |-
             You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
 
             - The unbanner's power level is insufficient to unban users from the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "errcode": "M_FORBIDDEN",
+              schema:
-                "error": "You do not have a high enough power level to unban from this room."
+                $ref: definitions/errors/error.yaml
-              }
+              examples:
-          schema:
+                response:
-            "$ref": "definitions/errors/error.yaml"
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You do not have a high enough power level to unban from this room."
+                  }
       tags:
         - Room membership
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/capabilities.yaml

@@ -11,21 +11,12 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Capabilities API"
+  title: Matrix Client-Server Capabilities API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/capabilities":
+  /capabilities:
     get:
       summary: Gets information about the server's capabilities.
       description: |-
@@ -34,79 +25,99 @@ paths:
       operationId: getCapabilities
       security:
         - accessToken: []
-      parameters: []
       responses:
-        200:
+        "200":
-          description:
+          description: The capabilities of the server.
-            The capabilities of the server.
+          content:
-          examples:
+            application/json:
-            application/json: {
+              schema:
-              "capabilities": {
-                "m.change_password": {
-                  "enabled": false
-                },
-                "m.room_versions": {
-                  "default": "1",
-                  "available": {
-                    "1": "stable",
-                    "2": "stable",
-                    "3": "unstable",
-                    "test-version": "unstable"
-                  }
-                },
-                "com.example.custom.ratelimit": {
-                  "max_requests_per_hour": 600
-                }
-              }
-            }
-          schema:
-            type: object
-            required: ["capabilities"]
-            properties:
-              capabilities:
                 type: object
-                title: Capabilities
+                required:
-                description: |-
+                  - capabilities
-                    The custom capabilities the server supports, using the
-                    Java package naming convention.
-                additionalProperties:
-                  type: object
                 properties:
-                  "m.change_password":
+                  capabilities:
                     type: object
+                    title: Capabilities
                     description: |-
-                      Capability to indicate if the user can change their password.
+                      The custom capabilities the server supports, using the
-                    title: ChangePasswordCapability
+                      Java package naming convention.
+                    additionalProperties:
+                      type: object
                     properties:
-                      enabled:
+                      m.change_password:
-                        type: boolean
-                        description: |-
-                          True if the user can change their password, false otherwise.
-                        example: false
-                    required: ['enabled']
-                  "m.room_versions":
-                    type: object
-                    description: The room versions the server supports.
-                    title: RoomVersionsCapability
-                    properties:
-                      default:
-                        type: string
-                        description: |-
-                          The default room version the server is using for new rooms.
-                        example: "1"
-                      available:
                         type: object
-                        description: |-
+                        description: Capability to indicate if the user can change their password.
-                          A detailed description of the room versions the server supports.
+                        title: ChangePasswordCapability
-                        additionalProperties:
+                        properties:
-                          type: string
+                          enabled:
-                          title: RoomVersionStability
+                            type: boolean
-                          enum: [stable, unstable]
+                            description: True if the user can change their password, false otherwise.
-                          description: The stability of the room version.
+                            example: false
-                    required: ['default', 'available']
+                        required:
-        429:
+                          - enabled
+                      m.room_versions:
+                        type: object
+                        description: The room versions the server supports.
+                        title: RoomVersionsCapability
+                        properties:
+                          default:
+                            type: string
+                            description: The default room version the server is using for new rooms.
+                            example: "1"
+                          available:
+                            type: object
+                            description: A detailed description of the room versions the server supports.
+                            additionalProperties:
+                              type: string
+                              title: RoomVersionStability
+                              enum:
+                                - stable
+                                - unstable
+                              description: The stability of the room version.
+                        required:
+                          - default
+                          - available
+              examples:
+                response:
+                  value: {
+                    "capabilities": {
+                      "m.change_password": {
+                        "enabled": false
+                      },
+                      "m.room_versions": {
+                        "default": "1",
+                        "available": {
+                          "1": "stable",
+                          "2": "stable",
+                          "3": "unstable",
+                          "test-version": "unstable"
+                        }
+                      },
+                      "com.example.custom.ratelimit": {
+                        "max_requests_per_hour": 600
+                      }
+                    }
+                  }
+        "429":
           description: This request was rate-limited.
-          schema:
+          content:
-            "$ref": "definitions/errors/rate_limited.yaml"
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Capabilities
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml