Merge remote-tracking branch 'upstream/main' into clokep/push-rules-scope

.github/ISSUE_TEMPLATE/release.md

@@ -1,6 +1,6 @@
 ---
-name: [SCT] Release checklist
+name: '[SCT] Release checklist'
-about: Used by the Spec Core Team to create a new release.
+about: 'Used by the Spec Core Team to create a new release.'
 title: 'Matrix 1.X'
 labels: 'release-blocker'
 assignees: ''
@@ -16,20 +16,22 @@ Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
 
 Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
 
+* [ ] Pin this issue to the repo.
 * [ ] Ensure the social media account holders are available for the release day.
-* [ ] Blog post written
+* [ ] Blog post written.
-* [ ] Check for release blockers that may have been missed
+* [ ] Check for release blockers that may have been missed.
-* [ ] Review/fix the changelog
+* [ ] Review/fix the changelog.
 
 Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
-* [ ] Branch stuffs
+* [ ] Branch stuffs.
-* [ ] Github release artifact
+* [ ] Github release artifact.
-* [ ] Published to spec.matrix.org
+* [ ] Published to spec.matrix.org.
-* [ ] All links work
+* [ ] All links work.
-* [ ] Publish blog post
+* [ ] Publish blog post.
-* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted
+* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted.
-* [ ] Post to Twitter/Mastodon
+* [ ] Post to Twitter/Mastodon.
-* [ ] Close this issue
+* [ ] Close this issue.
+* [ ] Unpin this issue from the repo.
 
 Known release blockers:
 * [ ] <!-- Issue/PR link -->

.github/workflows/main.yml

@@ -193,7 +193,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.113.0'
+          hugo-version: '0.117.0'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4

.github/workflows/netlify.yaml

@@ -25,8 +25,11 @@ jobs:
         id: readctx
         # we need to find the PR number that corresponds to the branch, which we do by
         # searching the GH API
+        env:
+          OWNER_LOGIN: ${{ github.event.workflow_run.head_repository.owner.login }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
         run: |
-          head_branch='${{github.event.workflow_run.head_repository.owner.login}}:${{github.event.workflow_run.head_branch}}'
+          head_branch="${OWNER_LOGIN}:${HEAD_BRANCH}"
           echo "head branch: $head_branch"
           pulls_uri="https://api.github.com/repos/${{ github.repository }}/pulls?head=$(jq -Rr '@uri' <<<$head_branch)"
           pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |

.htmltest.yaml

@@ -4,3 +4,4 @@
 IgnoreDirectoryMissingTrailingSlash: true
 DirectoryPath: spec
 CheckExternal: false
+IgnoreInternalEmptyHash: true

CONTRIBUTING.rst

@@ -99,6 +99,8 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``deprecation`` - Used when deprecating something.
 
+* ``removal`` - Used when removing something that was unused or previously deprecated.
+
 All news fragments must have a brief summary explaining the change in the
 contents of the file. The summary must end in a full stop to be in line with
 the style guide and formatting must be done using Markdown.
@@ -163,19 +165,6 @@ include the line in your commit or pull request comment::
 
     Signed-off-by: Your Name <your@email.example.org>
 
-...using your real name; unfortunately pseudonyms and anonymous contributions
+Git allows you to add this signoff automatically when using the ``-s``
-can't be accepted. Git makes this trivial - just use the -s flag when you do
+flag to ``git commit``, which uses the name and email set in your
-``git commit``, having first set ``user.name`` and ``user.email`` git configs
+``user.name`` and ``user.email`` git configs.
-(which you should have done anyway :)
-
-Private sign off
-~~~~~~~~~~~~~~~~
-
-If you would like to provide your legal name privately to the Matrix.org
-Foundation (instead of in a public commit or comment), you can do so by emailing
-your legal name and a link to the pull request to dco@matrix.org. It helps to
-include "sign off" or similar in the subject line. You will then be instructed
-further.
-
-Once private sign off is complete, doing so for future contributions will not
-be required.

README.md

@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.113.0 is required.
+   v0.117.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required

changelogs/appendices/newsfragments/1791.clarification

@@ -1 +0,0 @@
-Define 'Opaque Identifier Grammar'.

changelogs/appendices/newsfragments/1819.clarification

@@ -1 +0,0 @@
-Define common cryptographic key representation.

changelogs/appendices/newsfragments/1823.deprecation

@@ -1 +0,0 @@
-Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132).

changelogs/application_service/newsfragments/1772.clarification

@@ -1 +0,0 @@
-Fix the OpenAPI definition of the security schemes.

changelogs/application_service/newsfragments/1810.clarification

@@ -1 +0,0 @@
-Clarify that appservices should be notified of events relating to the sender_localpart user.

changelogs/client_server/newsfragments/1755.clarification

@@ -1 +0,0 @@
-Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291).

changelogs/client_server/newsfragments/1757.feature

@@ -1 +0,0 @@
-Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).

changelogs/client_server/newsfragments/1772.clarification

@@ -1 +0,0 @@
-Fix the OpenAPI definition of the security schemes.

changelogs/client_server/newsfragments/1776.clarification

@@ -1 +0,0 @@
-Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response.

changelogs/client_server/newsfragments/1808.clarification

@@ -1 +0,0 @@
-Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).

changelogs/client_server/newsfragments/1812.feature

@@ -1 +0,0 @@
-Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692).

changelogs/client_server/newsfragments/1813.clarification

@@ -1 +0,0 @@
-Use `patternProperties` in more places with supported formats.

changelogs/client_server/newsfragments/1816.clarification

@@ -1 +0,0 @@
-Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191).

changelogs/client_server/newsfragments/1819.clarification

@@ -1 +0,0 @@
-Rename "recovery key" to "backup decryption key".

changelogs/client_server/newsfragments/1822.clarification

@@ -1 +0,0 @@
-Refactor the OpenAPI definitions of the content repository endpoints.

changelogs/client_server/newsfragments/1829.clarification

@@ -1 +0,0 @@
-Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key).

changelogs/client_server/newsfragments/1855.clarification

@@ -0,0 +1 @@
+Rename and sort the modules in the feature profiles table for easier skimming.

changelogs/client_server/newsfragments/1870.removal

@@ -0,0 +1 @@
+Remove the deprecated name attribute on HTML anchor elements as per [MSC4159](https://github.com/matrix-org/matrix-spec-proposals/pull/4159).

changelogs/client_server/newsfragments/1871.clarification

@@ -0,0 +1 @@
+Clarify that room avatars cannot be encrypted.

changelogs/client_server/newsfragments/1875.clarification

@@ -0,0 +1 @@
+Document the acronyms and alternate names for the "Secrets" section.

changelogs/client_server/newsfragments/1888.clarification

@@ -0,0 +1 @@
+Improve recommendation for how to form transaction IDs.

changelogs/client_server/newsfragments/1890.clarification

@@ -0,0 +1 @@
+Clarify that the deprecated `dont_notify` and `coalesce` push rule actions MUST be ignored, not rejected.

changelogs/client_server/newsfragments/1895.feature

@@ -0,0 +1 @@
+Add support for marking rooms as unread as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867).

changelogs/client_server/newsfragments/1897.clarification

@@ -0,0 +1 @@
+Add missing references to `m.set_displayname`, `m.set_avatar_url` and `m.3pid_changes` in capabilities table.

changelogs/client_server/newsfragments/1899.clarification

@@ -0,0 +1 @@
+Clarify that the fallback login page calls `window.matrixLogin.onLogin` instead of `window.onLogin`.

changelogs/client_server/newsfragments/1903.clarification

@@ -0,0 +1 @@
+Remove confusing description of restricted rooms with no valid conditions.

changelogs/client_server/newsfragments/1905.clarification

@@ -0,0 +1 @@
+Clarify that `window.matrixLogin.onLogin` is called with the response body of `POST /_matrix/client/v3/login`.

changelogs/client_server/newsfragments/1908.clarification

@@ -0,0 +1 @@
+Document the `m.get_login_token` capability as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882).

changelogs/client_server/newsfragments/1909.clarification

@@ -0,0 +1 @@
+The `User identifier` object in `POST /_matrix/client/v3/login` contains additional properties that depend on the identification type.

changelogs/client_server/newsfragments/1910.clarification

@@ -0,0 +1 @@
+Don't mention that `GET /_matrix/client/v3/profile/{userId}` can return additional properties because this is true for almost every endpoint.

changelogs/identity_service/newsfragments/1772.clarification

@@ -1 +0,0 @@
-Fix the OpenAPI definition of the security schemes.

changelogs/identity_service/newsfragments/1808.clarification

@@ -1 +0,0 @@
-Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).

changelogs/internal/newsfragments/1765.clarification

@@ -1 +0,0 @@
-Fix npm release script for `@matrix-org/spec`.

changelogs/internal/newsfragments/1769.clarification

@@ -1 +0,0 @@
-Formatting fixes in CONTRIBUTING.rst.

changelogs/internal/newsfragments/1770.clarification

@@ -1 +0,0 @@
-Reduce whitespace on mobile viewports

changelogs/internal/newsfragments/1771.clarification

@@ -1 +0,0 @@
-Arrange rows in `.basic-info` tables vertically when horizontal space is constrained.

changelogs/internal/newsfragments/1773.clarification

@@ -1 +0,0 @@
-Simplify uses of `resolve-refs` partial.

changelogs/internal/newsfragments/1775.clarification

@@ -1 +0,0 @@
-Fix Hugo warnings.

changelogs/internal/newsfragments/1781.clarification

@@ -1 +0,0 @@
-Fix `github-labels.rst`

changelogs/internal/newsfragments/1786.clarification

@@ -1 +0,0 @@
-Upgrade jsonschema and python-jsonpath CI scripts dependencies.

changelogs/internal/newsfragments/1787.clarification

@@ -1 +0,0 @@
-Solve `allOf` recursively in OpenAPI and JSON Schemas.

changelogs/internal/newsfragments/1788.clarification

@@ -1 +0,0 @@
-Fix Hugo warnings.

changelogs/internal/newsfragments/1789.clarification

@@ -1 +0,0 @@
-Fix property type resolution in `render-object-table` partial.

changelogs/internal/newsfragments/1793.misc

@@ -1 +0,0 @@
-Factor out common definition of `Tag` type.

changelogs/internal/newsfragments/1794.clarification

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

changelogs/internal/newsfragments/1796.clarification

@@ -1 +0,0 @@
-Add support for pattern formats for `patternProperties`.

changelogs/internal/newsfragments/1797.clarification

@@ -1 +0,0 @@
-Clean up unnecessary `allOf`s in OpenAPI definitions.

changelogs/internal/newsfragments/1798.clarification

@@ -1 +0,0 @@
-Show information about "Additional Properties" in object tables.

changelogs/internal/newsfragments/1799.clarification

@@ -1 +0,0 @@
-Fix anchors for schemas under `oneOf`.

changelogs/internal/newsfragments/1800.clarification

@@ -1 +0,0 @@
-Use reference to `OneTimeKeys` schema in OpenAPI definitions.

changelogs/internal/newsfragments/1801.clarification

@@ -1 +0,0 @@
-Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`.

changelogs/internal/newsfragments/1802.clarification

@@ -1 +0,0 @@
-Add anchors in `definition` shortcode.

changelogs/internal/newsfragments/1803.clarification

@@ -1 +0,0 @@
-Update most CI actions.

changelogs/internal/newsfragments/1804.clarification

@@ -1 +0,0 @@
-Update typos CI action.

changelogs/internal/newsfragments/1805.clarification

@@ -1 +0,0 @@
-Set python version for the Towncrier CI job.

changelogs/internal/newsfragments/1806.clarification

@@ -1 +0,0 @@
-Replace `set-output` with environment files in CI.

changelogs/internal/newsfragments/1809.clarification

@@ -1 +0,0 @@
-Render response headers.

changelogs/internal/newsfragments/1814.clarification

@@ -1 +0,0 @@
-Add support for rendering string formats.

changelogs/internal/newsfragments/1831.clarification

@@ -1 +0,0 @@
-Clean up pull request template.

changelogs/internal/newsfragments/1886.clarification

@@ -0,0 +1 @@
+Clarified "real name" in contributor requirements to match other matrix-org projects.

changelogs/internal/newsfragments/1907.clarification

@@ -0,0 +1 @@
+Document the `removal` changelog category.

changelogs/internal/newsfragments/1914.clarification

@@ -0,0 +1 @@
+The Matrix.org Foundation no longer requires "real" or "legally identifiable" names in order to contribute to projects.

changelogs/room_versions/newsfragments/1824.clarification

@@ -1 +0,0 @@
-Clarify that redaction events are still subject to all applicable auth rules.

changelogs/room_versions/newsfragments/1827.clarification

@@ -1 +0,0 @@
-Fix minor spelling mistake of object being spelt "obiect".

changelogs/room_versions/newsfragments/1896.clarification.rst

@@ -0,0 +1 @@
+Fix a formatting issue in v2 state res.

changelogs/server_server/newsfragments/1772.clarification

@@ -1 +0,0 @@
-Fix the OpenAPI definition of the security schemes.

changelogs/server_server/newsfragments/1813.clarification

@@ -1 +0,0 @@
-Use `patternProperties` in more places with supported formats.

changelogs/server_server/newsfragments/1818.clarification

@@ -1 +0,0 @@
-Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list.

changelogs/server_server/newsfragments/1834.clarification

@@ -1 +0,0 @@
-Clarify that the `event` field of the `/v2/send_join` response is only required when `join_authorised_via_users_server` was present in the `content` field of the request.

config.toml

@@ -37,6 +37,10 @@ description = "Home of the Matrix specification for decentralised communication"
     weight = 30
 
 [markup]
+  [markup.tableOfContents]
+    startLevel = 2
+    endLevel = 6
+    ordered = true
   [markup.goldmark]
     [markup.goldmark.renderer]
       # Enables us to render raw HTML
@@ -66,8 +70,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 = "10"
+# minor = "11"
-# release_date = "March 22, 2024"
+# release_date = "June 20, 2024"
 
 # User interface configuration
 [params.ui]
@@ -130,7 +134,7 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.113.0"
+    min = "0.117.0"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false

content/appendices.md

@@ -556,7 +556,7 @@ The `domain` of a user ID is the [server name](#server-name) of the
 homeserver which allocated the account.
 
 The length of a user ID, including the `@` sigil and the domain, MUST
-NOT exceed 255 characters.
+NOT exceed 255 bytes.
 
 The complete grammar for a legal user ID is:
 
@@ -663,6 +663,9 @@ Room IDs are case-sensitive. They are not meant to be
 human-readable. They are intended to be treated as fully opaque strings
 by clients.
 
+The length of a room ID, including the `!` sigil and the domain, MUST
+NOT exceed 255 bytes.
+
 #### Room Aliases
 
 A room may have zero or more aliases. A room alias has the format:
@@ -673,8 +676,8 @@ The `domain` of a room alias is the [server name](#server-name) of the
 homeserver which created the alias. Other servers may contact this
 homeserver to look up the alias.
 
-Room aliases MUST NOT exceed 255 bytes (including the `#` sigil and the
+The length of a room alias, including the `#` sigil and the domain, MUST
-domain).
+NOT exceed 255 bytes.
 
 #### Event IDs
 
@@ -686,10 +689,12 @@ However, the precise format depends upon the [room version
 specification](/rooms): early room versions included a `domain` component,
 whereas more recent versions omit the domain and use a base64-encoded hash instead.
 
+In addition to the requirements of the room version, the length of an event ID,
+including the `$` sigil and the domain where present, MUST NOT exceed 255 bytes.
+
 Event IDs are case-sensitive. They are not meant to be human-readable. They are
 intended to be treated as fully opaque strings by clients.
 
-
 ### URIs
 
 There are two major kinds of referring to a resource in Matrix: matrix.to

content/changelog/v1.11.md

@@ -0,0 +1,170 @@
+---
+date: 2024-06-20T10:20:43-06:00
+---
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    v1.11  = Replaced by the version number (eg: v1.2)
+    June 20, 2024     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## v1.11
+
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.11">https://github.com/matrix-org/matrix-spec/tree/v1.11</a></td>
+<tr><th>Release date</th><td>June 20, 2024</td>
+</table>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
+
+### Client-Server API
+
+**Deprecations**
+
+- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808))
+- Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**New Endpoints**
+
+- [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**Backwards Compatible Changes**
+
+- Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). ([#1755](https://github.com/matrix-org/matrix-spec/issues/1755))
+- Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). ([#1757](https://github.com/matrix-org/matrix-spec/issues/1757))
+- Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692). ([#1812](https://github.com/matrix-org/matrix-spec/issues/1812))
+- Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). ([#1816](https://github.com/matrix-org/matrix-spec/issues/1816))
+- Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). ([#1828](https://github.com/matrix-org/matrix-spec/issues/1828))
+- Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). ([#1847](https://github.com/matrix-org/matrix-spec/issues/1847))
+- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**Spec Clarifications**
+
+- Add `/logout` and clarify the endpoints which do not take a JSON request body. ([#1644](https://github.com/matrix-org/matrix-spec/issues/1644))
+- Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response. ([#1776](https://github.com/matrix-org/matrix-spec/issues/1776))
+- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813))
+- Rename "recovery key" to "backup decryption key". ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819))
+- Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). ([#1829](https://github.com/matrix-org/matrix-spec/issues/1829))
+- Fix various typos throughout the specification. ([#1832](https://github.com/matrix-org/matrix-spec/issues/1832), [#1841](https://github.com/matrix-org/matrix-spec/issues/1841), [#1852](https://github.com/matrix-org/matrix-spec/issues/1852), [#1853](https://github.com/matrix-org/matrix-spec/issues/1853))
+- Specify the encoding to be used when generating QR codes for device verification. ([#1839](https://github.com/matrix-org/matrix-spec/issues/1839))
+- Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. ([#1843](https://github.com/matrix-org/matrix-spec/issues/1843))
+- Use RFC 2119 keywords more consistently. ([#1846](https://github.com/matrix-org/matrix-spec/issues/1846), [#1861](https://github.com/matrix-org/matrix-spec/issues/1861))
+- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850))
+- Clarify that relations recursion should be capped at a certain depth. ([#1854](https://github.com/matrix-org/matrix-spec/issues/1854))
+- Add missing secrets, third-party invites and room tagging modules to feature profiles table. ([#1860](https://github.com/matrix-org/matrix-spec/issues/1860))
+- Clarify when server name is used and link to the definition. ([#1862](https://github.com/matrix-org/matrix-spec/issues/1862))
+- Clarify where keys reside when checking an `m.room.encrypted` event. ([#1863](https://github.com/matrix-org/matrix-spec/issues/1863))
+- Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. ([#1872](https://github.com/matrix-org/matrix-spec/issues/1872))
+
+
+### Server-Server API
+
+**Deprecations**
+
+- Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**New Endpoints**
+
+- [`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**Backwards Compatible Changes**
+
+- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858), [#1869](https://github.com/matrix-org/matrix-spec/issues/1869))
+
+**Spec Clarifications**
+
+- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813))
+- Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. ([#1818](https://github.com/matrix-org/matrix-spec/issues/1818))
+- Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. ([#1834](https://github.com/matrix-org/matrix-spec/issues/1834), [#1840](https://github.com/matrix-org/matrix-spec/issues/1840))
+- Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. ([#1844](https://github.com/matrix-org/matrix-spec/issues/1844))
+- Fix various typos throughout the specification. ([#1877](https://github.com/matrix-org/matrix-spec/issues/1877))
+
+
+### Application Service API
+
+**Spec Clarifications**
+
+- Clarify that appservices should be notified of events relating to the `sender_localpart` user. ([#1810](https://github.com/matrix-org/matrix-spec/issues/1810))
+
+
+### Identity Service API
+
+**Deprecations**
+
+- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808))
+
+
+### Push Gateway API
+
+No significant changes.
+
+
+### Room Versions
+
+**Spec Clarifications**
+
+- Clarify that redaction events are still subject to all applicable auth rules. ([#1824](https://github.com/matrix-org/matrix-spec/issues/1824))
+- Fix various typos throughout the specification. ([#1827](https://github.com/matrix-org/matrix-spec/issues/1827), [#1848](https://github.com/matrix-org/matrix-spec/issues/1848))
+- Fix the rendering of the event format for room versions 1 and 2. ([#1883](https://github.com/matrix-org/matrix-spec/issues/1883))
+- Generate the Table of Contents with Hugo rather than JavaScript. ([#1884](https://github.com/matrix-org/matrix-spec/issues/1884))
+
+
+### Appendices
+
+**Deprecations**
+
+- Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132). ([#1823](https://github.com/matrix-org/matrix-spec/issues/1823))
+
+**Spec Clarifications**
+
+- Define 'Opaque Identifier Grammar'. ([#1791](https://github.com/matrix-org/matrix-spec/issues/1791))
+- Define common cryptographic key representation. ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819))
+- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850))
+
+
+### Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Update the spec release process and related documentation. ([#1759](https://github.com/matrix-org/matrix-spec/issues/1759))
+- Fix npm release script for `@matrix-org/spec`. ([#1765](https://github.com/matrix-org/matrix-spec/issues/1765))
+- Formatting fixes in `CONTRIBUTING.rst`. ([#1769](https://github.com/matrix-org/matrix-spec/issues/1769))
+- Improve rendering on mobile devices. ([#1770](https://github.com/matrix-org/matrix-spec/issues/1770), [#1771](https://github.com/matrix-org/matrix-spec/issues/1771))
+- Fix the OpenAPI definition of the security schemes. ([#1772](https://github.com/matrix-org/matrix-spec/issues/1772))
+- Simplify uses of `resolve-refs` partial. ([#1773](https://github.com/matrix-org/matrix-spec/issues/1773))
+- Fix Hugo warnings. ([#1775](https://github.com/matrix-org/matrix-spec/issues/1775), [#1788](https://github.com/matrix-org/matrix-spec/issues/1788))
+- Fix `github-labels.rst`. ([#1781](https://github.com/matrix-org/matrix-spec/issues/1781))
+- Update dependencies. ([#1786](https://github.com/matrix-org/matrix-spec/issues/1786), [#1803](https://github.com/matrix-org/matrix-spec/issues/1803), [#1804](https://github.com/matrix-org/matrix-spec/issues/1804))
+- Solve `allOf` recursively in OpenAPI and JSON Schemas. ([#1787](https://github.com/matrix-org/matrix-spec/issues/1787))
+- Fix property type resolution in `render-object-table` partial. ([#1789](https://github.com/matrix-org/matrix-spec/issues/1789))
+- Factor out common definition of `Tag` type. ([#1793](https://github.com/matrix-org/matrix-spec/issues/1793))
+- Update the version of Hugo used to render the spec to v0.124.1. ([#1794](https://github.com/matrix-org/matrix-spec/issues/1794))
+- Add support for pattern formats for `patternProperties`. ([#1796](https://github.com/matrix-org/matrix-spec/issues/1796))
+- Clean up unnecessary `allOf`s in OpenAPI definitions. ([#1797](https://github.com/matrix-org/matrix-spec/issues/1797))
+- Show information about "Additional Properties" in object tables. ([#1798](https://github.com/matrix-org/matrix-spec/issues/1798))
+- Fix anchors for schemas under `oneOf`. ([#1799](https://github.com/matrix-org/matrix-spec/issues/1799))
+- Use reference to `OneTimeKeys` schema in OpenAPI definitions. ([#1800](https://github.com/matrix-org/matrix-spec/issues/1800))
+- Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. ([#1801](https://github.com/matrix-org/matrix-spec/issues/1801))
+- Add anchors in `definition` shortcode. ([#1802](https://github.com/matrix-org/matrix-spec/issues/1802))
+- Set python version for the Towncrier CI job. ([#1805](https://github.com/matrix-org/matrix-spec/issues/1805))
+- Replace `set-output` with environment files in CI. ([#1806](https://github.com/matrix-org/matrix-spec/issues/1806))
+- Render response headers. ([#1809](https://github.com/matrix-org/matrix-spec/issues/1809))
+- Use `patternProperties` in more places with supported formats. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813))
+- Add support for rendering string formats. ([#1814](https://github.com/matrix-org/matrix-spec/issues/1814))
+- Refactor the OpenAPI definitions of the content repository endpoints. ([#1822](https://github.com/matrix-org/matrix-spec/issues/1822))
+- Clean up pull request template. ([#1831](https://github.com/matrix-org/matrix-spec/issues/1831))
+- Do not add empty arrays to examples. ([#1849](https://github.com/matrix-org/matrix-spec/issues/1849))
+- Generate the Table of Contents with Hugo rather than JavaScript. ([#1851](https://github.com/matrix-org/matrix-spec/issues/1851), [#1885](https://github.com/matrix-org/matrix-spec/issues/1885))
+- Fix syntax errors in the spec release issue template. ([#1856](https://github.com/matrix-org/matrix-spec/issues/1856))
+- Use environment variables for Netlify build job. ([#1865](https://github.com/matrix-org/matrix-spec/issues/1865))
+- Render added/changed in info on request and response content types. ([#1876](https://github.com/matrix-org/matrix-spec/issues/1876))
+- Fix validation errors in generated HTML. ([#1880](https://github.com/matrix-org/matrix-spec/issues/1880))
+- Ensure most generated HTML IDs are unique. ([#1881](https://github.com/matrix-org/matrix-spec/issues/1881))
+- Allow to specify a prefix for generated HTML IDs of API endpoints. ([#1882](https://github.com/matrix-org/matrix-spec/issues/1882))

content/client-server-api/_index.md

@@ -22,17 +22,23 @@ 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 [`POST
+All `POST` and `PUT` endpoints, with the exception of those listed below,
-/_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT
-/_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid),
 require the client to supply a request body containing a (potentially empty)
 JSON object.  Clients should supply a `Content-Type` header of
 `application/json` for all requests with JSON bodies, but this is not required.
 
+The exceptions are:
+
+- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and 
+  [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid),
+  both of which take the uploaded media as the request body.
+- [`POST /_matrix/client/v3/logout`](#post_matrixclientv3logout) and
+  [`POST /_matrix/client/v3/logout/all`](#post_matrixclientv3logoutall),
+  which take an empty request body.
+
 Similarly, all endpoints require the server to return a JSON object,
-with the exception of 200 responses to
+with the exception of 200 responses to the media download endpoints in the
-[`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid)
+[Content Repository module](#content-repository).
-and [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](#get_matrixmediav3thumbnailservernamemediaid).
 Servers must include a `Content-Type` header of `application/json` for all JSON responses.
 
 All JSON data, in requests or responses, must be encoded using UTF-8.
@@ -227,7 +233,7 @@ return a standard error response of the form:
 ```
 
 Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after)
-for any response with a 429 status code.
+header for any response with a 429 status code.
 
 The `retry_after_ms` property MAY be included to tell the client how long
 they have to wait in milliseconds before they can try again. This property is
@@ -245,9 +251,10 @@ the request idempotent.
 
 The transaction ID should **only** be used for this purpose.
 
-From the client perspective, after the request has finished, the `{txnId}`
+After the request has finished, clients should change the `{txnId}` value for
-value should be changed by for the next request (how is not specified; a
+the next request. How this is achieved, is left as an implementation detail.
-monotonically increasing integer is recommended).
+It is recommended that clients use either version 4 UUIDs or a concatenation
+of the current timestamp and a monotonically increasing integer.
 
 The homeserver should identify a request as a retransmission if the
 transaction ID is the same as a previous request, and the path of the
@@ -349,9 +356,9 @@ as per the [CORS](#web-browser-clients) section in this specification.
 The `.well-known` method uses a JSON file at a predetermined location to
 specify parameter values. The flow for this method is as follows:
 
-1.  Extract the server name from the user's Matrix ID by splitting the
+1.  Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the
     Matrix ID at the first colon.
-2.  Extract the hostname from the server name.
+2.  Extract the hostname from the server name as described by the [grammar](/appendices/#server-name).
 3.  Make a GET request to `https://hostname/.well-known/matrix/client`.
     1.  If the returned status code is 404, then `IGNORE`.
     2.  If the returned status code is not 200, or the response body is
@@ -1394,7 +1401,10 @@ fallback login API:
 
 This returns an HTML and JavaScript page which can perform the entire
 login process. The page will attempt to call the JavaScript function
-`window.onLogin` when login has been successfully completed.
+`window.matrixLogin.onLogin(response)` when login has been successfully
+completed. The argument, `response`, is the JSON response body of
+[`POST /_matrix/client/v3/login`](#post_matrixclientv3login) parsed
+into a JavaScript object.
 
 {{% added-in v="1.1" %}} Non-credential parameters valid for the `/login`
 endpoint can be provided as query string parameters here. These are to be
@@ -1644,6 +1654,27 @@ An example of the capability API's response for this capability is:
 }
 ```
 
+### `m.get_login_token` capability
+
+This capability has a single flag, `enabled`, to denote whether the user
+is able to use [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token)
+to generate single-use, time-limited tokens to log unauthenticated clients
+into their account.
+
+When not listed, clients SHOULD assume the user is unable to generate tokens.
+
+An example of the capability API's response for this capability is:
+
+```json
+{
+  "capabilities": {
+    "m.get_login_token": {
+      "enabled": false
+    }
+  }
+}
+```
+
 ## Filtering
 
 Filters can be created on the server and can be passed as a parameter to
@@ -1842,16 +1873,15 @@ updates not being sent.
 
 The complete event MUST NOT be larger than 65536 bytes, when formatted
 with the [federation event format](#room-event-format), including any
-signatures, and encoded as [Canonical
+signatures, and encoded as [Canonical JSON](/appendices#canonical-json).
-JSON](/appendices#canonical-json).
 
 There are additional restrictions on sizes per key:
 
--   `sender` MUST NOT exceed 255 bytes (including domain).
+-   `sender` MUST NOT exceed the size limit for [user IDs](/appendices/#user-identifiers).
--   `room_id` MUST NOT exceed 255 bytes.
+-   `room_id` MUST NOT exceed the size limit for [room IDs](/appendices/#room-ids).
 -   `state_key` MUST NOT exceed 255 bytes.
 -   `type` MUST NOT exceed 255 bytes.
--   `event_id` MUST NOT exceed 255 bytes.
+-   `event_id` MUST NOT exceed the size limit for [event IDs](/appendices/#event-ids).
 
 Some event types have additional size restrictions which are specified
 in the description of the event. Additional keys have no limit other
@@ -2316,7 +2346,7 @@ following endpoint.
 This endpoint is particularly useful if the client has lost context on the aggregation for
 a parent event and needs to rebuild/verify it.
 
-When using the `recurse` parameter, note that there no way for a client to
+When using the `recurse` parameter, note that there is no way for a client to
 control how far the server recurses. If the client decides that the server's
 recursion level is insufficient, it could, for example, perform the recursion
 itself, or disable whatever feature requires more recursion.
@@ -2565,9 +2595,6 @@ join is happening over federation, the remote server will check the conditions
 before accepting the join. See the [Server-Server Spec](/server-server-api/#restricted-rooms)
 for more information.
 
-If the room is `restricted` but no valid conditions are presented then the
-room is effectively invite only.
-
 The user does not need to maintain the conditions in order to stay a member
 of the room: the conditions are only checked/evaluated during the join process.
 
@@ -2721,42 +2748,45 @@ that profile.
 
 | Module / Profile                                           | Web       | Mobile   | Desktop  | CLI      | Embedded |
 |------------------------------------------------------------|-----------|----------|----------|----------|----------|
-| [Instant Messaging](#instant-messaging)                    | Required  | Required | Required | Required | Optional |
+| [Content Repository](#content-repository)                  | Required  | Required | Required | Optional | Optional |
-| [Rich replies](#rich-replies)                              | Optional  | Optional | Optional | Optional | Optional |
 | [Direct Messaging](#direct-messaging)                      | Required  | Required | Required | Required | Optional |
-| [Mentions](#user-and-room-mentions)                        | Required  | Required | Required | Optional | Optional |
+| [Ignoring Users](#ignoring-users)                          | Required  | Required | Required | Optional | Optional |
+| [Instant Messaging](#instant-messaging)                    | Required  | Required | Required | Required | Optional |
 | [Presence](#presence)                                      | Required  | Required | Required | Required | Optional |
 | [Push Notifications](#push-notifications)                  | Optional  | Required | Optional | Optional | Optional |
 | [Receipts](#receipts)                                      | Required  | Required | Required | Required | Optional |
-| [Fully read markers](#fully-read-markers)                  | Optional  | Optional | Optional | Optional | Optional |
+| [Room History Visibility](#room-history-visibility)        | Required  | Required | Required | Required | Optional |
-| [Typing Notifications](#typing-notifications)              | Required  | Required | Required | Required | Optional |
-| [VoIP](#voice-over-ip)                                     | Required  | Required | Required | Optional | Optional |
-| [Ignoring Users](#ignoring-users)                          | Required  | Required | Required | Optional | Optional |
-| [Reporting Content](#reporting-content)                    | Optional  | Optional | Optional | Optional | Optional |
-| [Content Repository](#content-repository)                  | Required  | Required | Required | Optional | Optional |
-| [Managing History Visibility](#room-history-visibility)    | Required  | Required | Required | Required | Optional |
-| [Server Side Search](#server-side-search)                  | Optional  | Optional | Optional | Optional | Optional |
 | [Room Upgrades](#room-upgrades)                            | Required  | Required | Required | Required | Optional |
-| [Server Administration](#server-administration)            | Optional  | Optional | Optional | Optional | Optional |
+| [Third-party Invites](#third-party-invites)                | Optional  | Required | Optional | Optional | Optional |
-| [Event Context](#event-context)                            | Optional  | Optional | Optional | Optional | Optional |
+| [Typing Notifications](#typing-notifications)              | Required  | Required | Required | Required | Optional |
-| [Third-party Networks](#third-party-networks)              | Optional  | Optional | Optional | Optional | Optional |
+| [User and Room Mentions](#user-and-room-mentions)          | Required  | Required | Required | Optional | Optional |
-| [Send-to-Device Messaging](#send-to-device-messaging)      | Optional  | Optional | Optional | Optional | Optional |
+| [Voice over IP](#voice-over-ip)                            | Required  | Required | Required | Optional | Optional |
+| [Client Config](#client-config)                            | Optional  | Optional | Optional | Optional | Optional |
 | [Device Management](#device-management)                    | Optional  | Optional | Optional | Optional | Optional |
 | [End-to-End Encryption](#end-to-end-encryption)            | Optional  | Optional | Optional | Optional | Optional |
-| [Guest Accounts](#guest-access)                            | Optional  | Optional | Optional | Optional | Optional |
-| [Room Previews](#room-previews)                            | Optional  | Optional | Optional | Optional | Optional |
-| [Client Config](#client-config)                            | Optional  | Optional | Optional | Optional | Optional |
-| [SSO Login](#sso-client-loginauthentication)               | Optional  | Optional | Optional | Optional | Optional |
-| [OpenID](#openid)                                          | Optional  | Optional | Optional | Optional | Optional |
-| [Stickers](#sticker-messages)                              | Optional  | Optional | Optional | Optional | Optional |
-| [Server ACLs](#server-access-control-lists-acls-for-rooms) | Optional  | Optional | Optional | Optional | Optional |
-| [Server Notices](#server-notices)                          | Optional  | Optional | Optional | Optional | Optional |
-| [Moderation policies](#moderation-policy-lists)            | Optional  | Optional | Optional | Optional | Optional |
-| [Spaces](#spaces)                                          | Optional  | Optional | Optional | Optional | Optional |
-| [Event Replacements](#event-replacements)                  | Optional  | Optional | Optional | Optional | Optional |
 | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional  | Optional | Optional | Optional | Optional |
-| [Threading](#threading)                                    | Optional  | Optional | Optional | Optional | Optional |
+| [Event Context](#event-context)                            | Optional  | Optional | Optional | Optional | Optional |
+| [Event Replacements](#event-replacements)                  | Optional  | Optional | Optional | Optional | Optional |
+| [Read and Unread Markers](#read-and-unread-markers)        | Optional  | Optional | Optional | Optional | Optional |
+| [Guest Access](#guest-access)                              | Optional  | Optional | Optional | Optional | Optional |
+| [Moderation Policy Lists](#moderation-policy-lists)        | Optional  | Optional | Optional | Optional | Optional |
+| [OpenID](#openid)                                          | Optional  | Optional | Optional | Optional | Optional |
 | [Reference Relations](#reference-relations)                | Optional  | Optional | Optional | Optional | Optional |
+| [Reporting Content](#reporting-content)                    | Optional  | Optional | Optional | Optional | Optional |
+| [Rich replies](#rich-replies)                              | Optional  | Optional | Optional | Optional | Optional |
+| [Room Previews](#room-previews)                            | Optional  | Optional | Optional | Optional | Optional |
+| [Room Tagging](#room-tagging)                              | Optional  | Optional | Optional | Optional | Optional |
+| [SSO Client Login/Authentication](#sso-client-loginauthentication) | Optional  | Optional | Optional | Optional | Optional |
+| [Secrets](#secrets)                                        | Optional  | Optional | Optional | Optional | Optional |
+| [Send-to-Device Messaging](#send-to-device-messaging)      | Optional  | Optional | Optional | Optional | Optional |
+| [Server Access Control Lists (ACLs)](#server-access-control-lists-acls-for-rooms) | Optional  | Optional | Optional | Optional | Optional |
+| [Server Administration](#server-administration)            | Optional  | Optional | Optional | Optional | Optional |
+| [Server Notices](#server-notices)                          | Optional  | Optional | Optional | Optional | Optional |
+| [Server Side Search](#server-side-search)                  | Optional  | Optional | Optional | Optional | Optional |
+| [Spaces](#spaces)                                          | Optional  | Optional | Optional | Optional | Optional |
+| [Sticker Messages](#sticker-messages)                      | Optional  | Optional | Optional | Optional | Optional |
+| [Third-party Networks](#third-party-networks)              | Optional  | Optional | Optional | Optional | Optional |
+| [Threading](#threading)                                    | Optional  | Optional | Optional | Optional | Optional |
 
 *Please see each module for more details on what clients need to
 implement.*
@@ -2805,42 +2835,42 @@ operations and run in a resource constrained environment. Like embedded
 applications, they are not intended to be fully-fledged communication
 systems.
 
-{{< cs-module name="instant_messaging" >}}
+{{% cs-module name="instant_messaging" %}}
-{{< cs-module name="rich_replies" >}}
+{{% cs-module name="rich_replies" %}}
-{{< cs-module name="voip_events" >}}
+{{% cs-module name="voip_events" %}}
-{{< cs-module name="typing_notifications" >}}
+{{% cs-module name="typing_notifications" %}}
-{{< cs-module name="receipts" >}}
+{{% cs-module name="receipts" %}}
-{{< cs-module name="read_markers" >}}
+{{% cs-module name="read_markers" %}}
-{{< cs-module name="presence" >}}
+{{% cs-module name="presence" %}}
-{{< cs-module name="content_repo" >}}
+{{% cs-module name="content_repo" %}}
-{{< cs-module name="send_to_device" >}}
+{{% cs-module name="send_to_device" %}}
-{{< cs-module name="device_management" >}}
+{{% cs-module name="device_management" %}}
-{{< cs-module name="end_to_end_encryption" >}}
+{{% cs-module name="end_to_end_encryption" %}}
-{{< cs-module name="secrets" >}}
+{{% cs-module name="secrets" %}}
-{{< cs-module name="history_visibility" >}}
+{{% cs-module name="history_visibility" %}}
-{{< cs-module name="push" >}}
+{{% cs-module name="push" %}}
-{{< cs-module name="third_party_invites" >}}
+{{% cs-module name="third_party_invites" %}}
-{{< cs-module name="search" >}}
+{{% cs-module name="search" %}}
-{{< cs-module name="guest_access" >}}
+{{% cs-module name="guest_access" %}}
-{{< cs-module name="room_previews" >}}
+{{% cs-module name="room_previews" %}}
-{{< cs-module name="tags" >}}
+{{% cs-module name="tags" %}}
-{{< cs-module name="account_data" >}}
+{{% cs-module name="account_data" %}}
-{{< cs-module name="admin" >}}
+{{% cs-module name="admin" %}}
-{{< cs-module name="event_context" >}}
+{{% cs-module name="event_context" %}}
-{{< cs-module name="sso_login" >}}
+{{% cs-module name="sso_login" %}}
-{{< cs-module name="dm" >}}
+{{% cs-module name="dm" %}}
-{{< cs-module name="ignore_users" >}}
+{{% cs-module name="ignore_users" %}}
-{{< cs-module name="stickers" >}}
+{{% cs-module name="stickers" %}}
-{{< cs-module name="report_content" >}}
+{{% cs-module name="report_content" %}}
-{{< cs-module name="third_party_networks" >}}
+{{% cs-module name="third_party_networks" %}}
-{{< cs-module name="openid" >}}
+{{% cs-module name="openid" %}}
-{{< cs-module name="server_acls" >}}
+{{% cs-module name="server_acls" %}}
-{{< cs-module name="mentions" >}}
+{{% cs-module name="mentions" %}}
-{{< cs-module name="room_upgrades" >}}
+{{% cs-module name="room_upgrades" %}}
-{{< cs-module name="server_notices" >}}
+{{% cs-module name="server_notices" %}}
-{{< cs-module name="moderation_policies" >}}
+{{% cs-module name="moderation_policies" %}}
-{{< cs-module name="spaces" >}}
+{{% cs-module name="spaces" %}}
-{{< cs-module name="event_replacements" >}}
+{{% cs-module name="event_replacements" %}}
-{{< cs-module name="event_annotations" >}}
+{{% cs-module name="event_annotations" %}}
-{{< cs-module name="threading" >}}
+{{% cs-module name="threading" %}}
-{{< cs-module name="reference_relations" >}}
+{{% cs-module name="reference_relations" %}}

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

@@ -23,19 +23,67 @@ When serving content, the server SHOULD provide a
 interacting with the media repository.
 {{% /boxes/added-in-paragraph %}}
 
+{{% boxes/added-in-paragraph %}}
+{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been
+deprecated in favour of newer, authenticated, ones. This change includes updating
+the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`,
+with the exception of the `/upload` and `/create` endpoints. The upload/create
+endpoints are expected to undergo a similar transition in a later version of the
+specification.
+{{% /boxes/added-in-paragraph %}}
+
 #### Matrix Content (`mxc://`) URIs
 
 Content locations are represented as Matrix Content (`mxc://`) URIs. They
 look like:
 
-    mxc://<server-name>/<media-id>
+```
+mxc://<server-name>/<media-id>
 
-    <server-name> : The name of the homeserver where this content originated, e.g. matrix.org
+<server-name> : The name of the homeserver where this content originated, e.g. matrix.org
-    <media-id> : An opaque ID which identifies the content.
+<media-id> : An opaque ID which identifies the content.
+```
 
-#### Client behaviour
+#### Client behaviour {id="content-repo-client-behaviour"}
 
-Clients can upload and download content using the following HTTP APIs.
+Clients can access the content repository using the following endpoints.
+
+{{% boxes/added-in-paragraph %}}
+{{< changed-in v="1.11" >}} Clients SHOULD NOT use the deprecated media endpoints
+described below. Instead, they SHOULD use the new endpoints which require authentication.
+{{% /boxes/added-in-paragraph %}}
+
+{{% boxes/warning %}}
+By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints
+to prevent newly-uploaded media from being downloaded. This SHOULD mean that any
+media uploaded *before* the freeze remains accessible via the deprecated endpoints,
+and any media uploaded *after* (or *during*) the freeze SHOULD only be accessible
+through the new, authenticated, endpoints. For remote media, "newly-uploaded" is
+determined by the date the cache was populated. This may mean the media is older
+than the freeze, but because the server had to re-download it, it is now considered
+"new".
+
+Clients SHOULD update to support the authenticated endpoints before servers freeze
+unauthenticated access.
+
+Servers SHOULD consider their local ecosystem impact before enacting a freeze.
+This could mean ensuring their users' typical clients support the new endpoints
+when available, or updating bridges to start using media proxies.
+
+In addition to the above, servers SHOULD exclude [IdP icons used in the `m.login.sso` flow](/client-server-api/#definition-mloginsso-flow-schema)
+from the freeze. See the `m.login.sso` flow schema for details.
+
+An *example* timeline for a server may be:
+
+* Matrix 1.11 release: Clients begin supporting authenticated media.
+* Matrix 1.12 release: Servers freeze unauthenticated media access.
+  * Media uploaded prior to this point still works with the deprecated endpoints.
+  * Newly uploaded (or cached) media *only* works on the authenticated endpoints.
+
+Matrix 1.12 is expected to be released in the July-September 2024 calendar quarter.
+{{% /boxes/warning %}}
+
+{{% http-api spec="client-server" api="authed-content-repo" %}}
 
 {{% http-api spec="client-server" api="content-repo" %}}
 

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

@@ -1179,10 +1179,16 @@ The process between Alice and Bob verifying each other would be:
 
 ###### QR code format
 
-The QR codes to be displayed and scanned using this format will encode binary
+The QR codes to be displayed and scanned MUST be
-strings in the general form:
+compatible with [ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html) and
+contain a single segment that uses the byte mode encoding.
 
-- the ASCII string `MATRIX`
+The error correction level can be chosen by the device displaying the QR code.
+
+The binary segment MUST be of the following form:
+
+- the string `MATRIX` encoded as one ASCII byte per character (i.e. `0x4D`,
+  `0x41`, `0x54`, `0x52`, `0x49`, `0x58`)
 - one byte indicating the QR code version (must be `0x02`)
 - one byte indicating the QR code verification mode.  Should be one of the
   following values:
@@ -1194,23 +1200,23 @@ strings in the general form:
   request event, encoded as:
   - two bytes in network byte order (big-endian) indicating the length in
     bytes of the ID as a UTF-8 string
-  - the ID as a UTF-8 string
+  - the ID encoded as a UTF-8 string
 - the first key, as 32 bytes.  The key to use depends on the mode field:
   - if `0x00` or `0x01`, then the current user's own master cross-signing public key
   - if `0x02`, then the current device's Ed25519 signing key
 - the second key, as 32 bytes.  The key to use depends on the mode field:
   - if `0x00`, then what the device thinks the other user's master
-    cross-signing key is
+    cross-signing public key is
   - if `0x01`, then what the device thinks the other device's Ed25519 signing
+    public key is
+  - if `0x02`, then what the device thinks the user's master cross-signing public
     key is
-  - if `0x02`, then what the device thinks the user's master cross-signing key
+- a random shared secret, as a sequence of bytes.  It is suggested to use a secret
-    is
-- a random shared secret, as a byte string.  It is suggested to use a secret
   that is about 8 bytes long.  Note: as we do not share the length of the
   secret, and it is not a fixed size, clients will just use the remainder of
-  binary string as the shared secret.
+  binary segment as the shared secret.
 
-For example, if Alice displays a QR code encoding the following binary string:
+For example, if Alice displays a QR code encoding the following binary data:
 
 ```
       "MATRIX"    |ver|mode| len   | event ID
@@ -1343,7 +1349,7 @@ the following format:
 The `session_data` field in the backups is constructed as follows:
 
 1.  Encode the session key to be backed up as a JSON object using the
-    `SessionData` format defined below.
+    `BackedUpSessionData` format defined below.
 
 2.  Generate an ephemeral curve25519 key, and perform an ECDH with the
     ephemeral key and the backup's public key to generate a shared
@@ -1421,7 +1427,7 @@ user-supplied passphrase, and is created as follows:
 
 ###### Key export format
 
-The exported sessions are formatted as a JSON array of `SessionData`
+The exported sessions are formatted as a JSON array of `ExportedSessionData`
 objects described as follows:
 
 {{% definition path="api/client-server/definitions/megolm_export_session_data" %}}
@@ -1530,9 +1536,11 @@ claiming to have sent messages which they didn't. `sender` must
 correspond to the user who sent the event, `recipient` to the local
 user, and `recipient_keys` to the local ed25519 key.
 
-Clients must confirm that the `sender_key` and the `ed25519` field value
+Clients must confirm that the `sender_key` property in the cleartext
-under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) for
+`m.room.encrypted` event body, and the `keys.ed25519` property in the
-the given user, and must also verify the signature of the keys from the
+decrypted plaintext, match the keys returned by
+[`/keys/query`](#post_matrixclientv3keysquery) for
+the given user. Clients must also verify the signature of the keys from the
 `/keys/query` response. Without this check, a client cannot be sure that
 the sender device owns the private part of the ed25519 key it claims to
 have in the Olm payload. This is crucial when the ed25519 key corresponds

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

@@ -74,7 +74,7 @@ the tag.
 | Tag    | Permitted Attributes                                                                                                                       |
 |--------|--------------------------------------------------------------------------------------------------------------------------------------------|
 | `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)), `data-mx-maths` (see [mathematical messages](#mathematical-messages)) |
-| `a`    | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) |
+| `a`    | `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`)         |
 | `img`  | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (`mxc://`) URI](#matrix-content-mxc-uris))                      |
 | `ol`   | `start`                                                                                                                                    |
 | `code` | `class` (only classes which start with `language-` for syntax highlighting)                                                                |

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

@@ -184,11 +184,13 @@ 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 %}}
+###### Historical Actions
+
 Older versions of the Matrix specification included the `dont_notify` and
-`coalesce` actions. These should both be considered no-ops (ignored, not
+`coalesce` actions. Clients and homeservers MUST ignore these actions, for
-rejected) if received from a client.
+instance, by stripping them from actions arrays they encounter. This means,
-{{% /boxes/note %}}
+for example, that a rule with `["dont_notify"]` actions MUST be equivalent
+to a rule with an empty actions array.
 
 ##### Conditions
 
@@ -521,7 +523,7 @@ Definition:
 }
 ```
 
-<a id="_m_rule_is_user_mention"/> **`.m.rule.is_user_mention`**
+<a id="_m_rule_is_user_mention"></a> **`.m.rule.is_user_mention`**
 
 {{< added-in v="1.7" >}}
 
@@ -555,7 +557,7 @@ Definition:
 }
 ```
 
-<a id="_m_rule_contains_display_name"/> **`.m.rule.contains_display_name`**
+<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**
 
 {{% changed-in v="1.7" %}}
 
@@ -590,7 +592,7 @@ Definition:
 }
 ```
 
-<a id="_m_rule_is_room_mention"/> **`.m.rule.is_room_mention`**
+<a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
 
 {{< added-in v="1.7" >}}
 
@@ -624,7 +626,7 @@ Definition:
 }
 ```
 
-<a id="_m_rule_roomnotif"/> **`.m.rule.roomnotif`**
+<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**
 
 {{% changed-in v="1.7" %}}
 
@@ -662,7 +664,7 @@ Definition:
 }
 ```
 
-**<a name="mruletombstone"></a>`.m.rule.tombstone`**
+**<a id="mruletombstone"></a>`.m.rule.tombstone`**
 
 Matches any state event whose type is `m.room.tombstone`. This is
 intended to notify users of a room when it is upgraded, similar to what
@@ -696,7 +698,7 @@ Definition:
 }
 ```
 
-**<a name="mrulereaction"></a>`.m.rule.reaction`**
+**<a id="mrulereaction"></a>`.m.rule.reaction`**
 
 {{% added-in v="1.7" %}}
 
@@ -776,7 +778,7 @@ Definition:
 
 ##### Default Content Rules
 
-<a id="_m_rule_contains_user_name"/> **`.m.rule.contains_user_name`**
+<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**
 
 {{% changed-in v="1.7" %}}
 

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

@@ -1,5 +1,6 @@
+### Read and unread markers
 
-### Fully read markers
+#### Fully read markers
 
 The history for a given room may be split into three sections: messages
 the user has read (or indicated they aren't interested in them),
@@ -8,7 +9,7 @@ user hasn't seen yet. The "fully read marker" (also known as a "read
 marker") marks the last event of the first section, whereas the user's
 read receipt marks the last event of the second section.
 
-#### Events
+##### Events
 
 The user's fully read marker is kept as an event in the room's [account
 data](#client-config). The event may be read to determine the user's
@@ -22,7 +23,7 @@ should be considered to be the user's read receipt location.
 
 {{% event event="m.fully_read" %}}
 
-#### Client behaviour
+##### Client behaviour
 
 The client cannot update fully read markers by directly modifying the
 `m.fully_read` account data event. Instead, the client must make use of
@@ -41,7 +42,7 @@ might wish to save an extra HTTP call. Providing `m.read` and/or
 
 {{% http-api spec="client-server" api="read_markers" %}}
 
-#### Server behaviour
+##### Server behaviour
 
 The server MUST prevent clients from setting `m.fully_read` directly in
 room account data. The server must additionally ensure that it treats
@@ -53,3 +54,44 @@ Upon updating the `m.fully_read` event due to a request to
 `/read_markers`, the server MUST send the updated account data event
 through to the client via the event stream (eg: `/sync`), provided any
 applicable filters are also satisfied.
+
+#### Unread markers
+
+Clients may use "unread markers" to allow users to label rooms for later
+attention irrespective of [read receipts](#receipts) or
+[fully read markers](#fully-read-markers).
+
+##### Events
+
+The user's unread marker in a room is kept under an `m.marked_unread`
+event in the room's [account data](#client-config). The event may be read
+to determine the user's current unread marker state in the room. Just
+like other account data events, the event will be pushed down the event
+stream when updated.
+
+{{% event event="m.marked_unread" %}}
+
+##### Client behaviour
+
+Clients MUST update unread markers by directly modifying the `m.marked_unread`
+room account data event. When marking a room as unread, clients SHOULD NOT change
+the `m.fully_read` marker, so that the user's read position in the room is
+retained.
+
+When the `unread` field is `true`, clients SHOULD visually annotate the room
+to indicate that it is unread. Exactly how this is achieved is left as an
+implementation detail. It is RECOMMENDED that clients use a treatment similar
+to how they represent rooms with unread notifications.
+
+Clients SHOULD reset the unread marker by setting `unread` to `false` when
+opening a room to display its timeline.
+
+Clients that offer functionality to mark a room as _read_ by sending a read
+receipt for the last event, SHOULD reset the unread marker simultaneously.
+
+If the `m.marked_unread` event does not exist on the user's account data,
+clients MUST behave as if `unread` was `false`.
+
+##### Server behaviour
+
+Servers have no additional requirements placed on them by this submodule.

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

@@ -21,7 +21,7 @@ Clients can of course also call other endpoints such as [GET
 and [GET /search](#post_matrixclientv3search) to
 access events outside the `/events` stream.
 
-{{% http-api spec="client-server" api="peeking_events" %}}
+{{% http-api spec="client-server" api="peeking_events" anchor_base="peeking" %}}
 
 #### Server behaviour
 

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

@@ -15,6 +15,9 @@ secret when storing, fetching, requesting, or sharing the secret.
 Secrets are plain strings; structured data can be stored by encoding it
 as a string.
 
+The mechanism described in this section is known as "secure secret storage and
+sharing", "SSSS", or "4S".
+
 #### Storage
 
 When secrets are stored on the server, they are stored in the user's

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

@@ -123,8 +123,8 @@ authentication is successful, the browser will be redirected to that
 
     For example, consider a web-based client at
     `https://client.example.com`, which wants to initiate SSO login on
-    the homeserver at `server.example.org`. It does this by storing the
+    the homeserver with [server name](/appendices/#server-name) `server.example.org`. It does this by storing the
-    homeserver name in a query parameter for the `redirectUrl`: it
+    server name in a query parameter for the `redirectUrl`: it
     redirects to
     `https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=server.example.org`.
 

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

@@ -33,7 +33,7 @@ invitee does indeed own that third-party identifier. See the
 
 A client asks a server to invite a user by their third-party identifier.
 
-{{% http-api spec="client-server" api="third_party_membership" %}}
+{{% http-api spec="client-server" api="third_party_membership" anchor_base="thirdparty" %}}
 
 #### Server behaviour
 

content/rooms/fragments/v2-state-res.md

@@ -138,7 +138,7 @@ The *resolution* of a set of states is obtained as follows:
 1.  Select the set *X* of all *power events* that appear in the *full
     conflicted set*. For each such power event *P*, enlarge *X* by adding
     the events in the auth chain of *P* which also belong to the full
-    conflicted set. Sort $X$ into a list using the *reverse topological
+    conflicted set. Sort *X* into a list using the *reverse topological
     power ordering*.
 2.  Apply the *iterative auth checks algorithm*, starting from the
     *unconflicted state map*, to the list of events from the previous

content/rooms/fragments/v3-auth-rules.md

@@ -1,6 +1,6 @@
 ---
 ---
-{{< added-in this=true >}} In room versions 1 and 2, events need a
+{{< added-in v=3 >}} In room versions 1 and 2, events need a
 signature from the domain of the `event_id` in order to be considered
 valid. This room version does not include an `event_id` over federation
 in the same respect, so does not need a signature from that server.

content/rooms/fragments/v3-handling-redactions.md

@@ -1,6 +1,6 @@
 ---
 ---
-{{% added-in this=true %}} In room versions 1 and 2, redactions were
+{{% added-in v=3 %}} In room versions 1 and 2, redactions were
 explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
 under Rule 11. As of room version 3, these conditions no longer exist as
 represented by [this version's authorization rules](#authorization-rules).

content/rooms/fragments/v4-event-ids.md

@@ -1,6 +1,6 @@
 ---
 ---
-{{% added-in this=true %}} The event ID is the [reference
+{{% added-in v=4 %}} The event ID is the [reference
 hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
 the event encoded using a variation of [Unpadded
 Base64](/appendices#unpadded-base64) which replaces the 62nd and

content/rooms/fragments/v8-auth-rules.md

@@ -54,7 +54,7 @@ The rules are as follows:
 4.  If type is `m.room.member`:
     1.  If there is no `state_key` property, or no `membership` property in
         `content`, reject.
-    2.  {{< added-in this=true >}}
+    2.  {{< added-in v=8 >}}
         If `content` has a `join_authorised_via_users_server` property:
         1.  If the event is not validly signed by the homeserver of the user ID denoted
             by the key, reject.
@@ -65,7 +65,7 @@ The rules are as follows:
         3.  If the `sender` is banned, reject.
         4.  If the `join_rule` is `invite` or `knock` then allow if
             membership state is `invite` or `join`.
-        5.  {{< added-in this=true >}}
+        5.  {{< added-in v=8 >}}
             If the `join_rule` is `restricted`:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`

content/rooms/v1.md

@@ -2,6 +2,7 @@
 title: Room Version 1
 type: docs
 weight: 10
+version: 1
 ---
 
 This room version is the first ever version for rooms, and contains the

content/rooms/v10.md

@@ -2,6 +2,7 @@
 title: Room Version 10
 type: docs
 weight: 100
+version: 10
 ---
 
 This room version builds on [version 9](/rooms/v9) to enforce that power level
@@ -140,7 +141,7 @@ The rules are as follows:
         3.  If the `sender` is banned, reject.
         4.  If the `join_rule` is `invite` or `knock` then allow if
             membership state is `invite` or `join`.
-        5.  {{< changed-in this="true" >}}
+        5.  {{< changed-in v=10 >}}
             If the `join_rule` is `restricted` or `knock_restricted`:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`
@@ -196,7 +197,7 @@ The rules are as follows:
             than the `sender`'s power level, allow.
         3.  Otherwise, reject.
     7. If `membership` is `knock`:
-        1.  {{< changed-in this="true" >}}
+        1.  {{< changed-in v=10 >}}
             If the `join_rule` is anything other than `knock` or
             `knock_restricted`, reject.
         2.  If `sender` does not match `state_key`, reject.
@@ -213,11 +214,11 @@ The rules are as follows:
 8.  If the event has a `state_key` that starts with an `@` and does not
     match the `sender`, reject.
 9. If type is `m.room.power_levels`:
-    1.  {{< added-in this="true" >}}
+    1.  {{< added-in v=10 >}}
         If any of the properties `users_default`, `events_default`, `state_default`,
         `ban`, `redact`, `kick`, or `invite` in `content` are present and
         not an integer, reject.
-    2.  {{< added-in this="true" >}}
+    2.  {{< added-in v=10 >}}
         If either of the properties `events` or `notifications` in `content`
         are present and not an object with values that are integers,
         reject.

content/rooms/v11.md

@@ -2,6 +2,7 @@
 title: Room Version 11
 type: docs
 weight: 100
+version: 11
 ---
 
 This room version builds on [version 10](/rooms/v10) while clarifying redaction
@@ -11,7 +12,7 @@ rules.
 
 ### Redactions
 
-{{< added-in this=true >}} The top-level `origin`, `membership`, and `prev_state` properties
+{{< added-in v=11 >}} The top-level `origin`, `membership`, and `prev_state` properties
 are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate)
 event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction)
 event keeps the `redacts` property under `content`. The
@@ -72,7 +73,7 @@ The `redacts` property of `m.room.redaction` events is moved from a top-level
 event property to a property under the event `content`.
 
 For backwards-compatibility with older clients, servers should add a `redacts` property
-to the top level of `m.room.redaction` events in when serving such events over the
+to the top level of `m.room.redaction` events when serving such events over the
 Client-Server API.
 
 For improved compatibility with newer clients, servers should add a `redacts` property
@@ -111,7 +112,7 @@ the [Handling redactions](#handling-redactions) section.
 
 The rules are as follows:
 
-1.  {{< changed-in this="true" >}}
+1.  {{< changed-in v=11 >}}
     If type is `m.room.create`:
     1.  If it has any `prev_events`, reject.
     2.  If the domain of the `room_id` does not match the domain of the
@@ -141,7 +142,7 @@ The rules are as follows:
         1.  If the event is not validly signed by the homeserver of the user ID denoted
             by the key, reject.
     3.  If `membership` is `join`:
-        1.  {{< changed-in this="true" >}}
+        1.  {{< changed-in v=11 >}}
             If the only previous event is an `m.room.create` and the
             `state_key` is the sender, allow.
         2.  If the `sender` does not match `state_key`, reject.

content/rooms/v2.md

@@ -2,6 +2,7 @@
 title: Room Version 2
 type: docs
 weight: 20
+version: 2
 ---
 
 This room version builds on [version 1](/rooms/v1) with an improved
@@ -27,7 +28,7 @@ changing only the state resolution algorithm.
 
 ### State resolution
 
-{{% added-in this=true %}}
+{{% added-in v=2 %}}
 
 {{% rver-fragment name="v2-state-res" %}}
 

content/rooms/v3.md

@@ -2,6 +2,7 @@
 title: Room Version 3
 type: docs
 weight: 30
+version: 3
 ---
 
 This room version builds on [version 2](/rooms/v2) with an improved event
@@ -39,8 +40,7 @@ all the remaining behaviour described by [room version 2](/rooms/v2).
 
 ### Handling redactions
 
-<!-- set withVersioning=true so we get all the "new in this version" stuff -->
+{{% rver-fragment name="v3-handling-redactions" %}}
-{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
 
 ### Event IDs
 
@@ -54,7 +54,7 @@ the use of a dedicated event ID, servers are required to track the
 hashes on an event to determine its ID.
 {{% /boxes/rationale %}}
 
-{{% added-in this=true %}} The event ID is the [reference
+{{% added-in v=3 %}} The event ID is the [reference
 hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
 the event encoded using [Unpadded
 Base64](/appendices#unpadded-base64), prefixed with `$`. A
@@ -90,7 +90,7 @@ The complete structure of a event in a v3 room is shown below.
 ### Authorization rules
 
 {{% boxes/note %}}
-{{< added-in this=true >}} `m.room.redaction` events are subject to auth rules in
+{{< added-in v=3 >}} `m.room.redaction` events are subject to auth rules in
 the same way as any other event. In practice, that means they will normally be allowed
 by the auth rules, unless the `m.room.power_levels` event sets a power level requirement
 for `m.room.redaction`events via the `events` or `events_default` properties. In
@@ -101,8 +101,7 @@ be performed. Receiving servers must perform additional checks, as described in
 the [Handling Redactions](#handling-redactions) section.
 {{% /boxes/note %}}
 
-<!-- set withVersioning=true so we get all the "new in this version" stuff -->
+{{% rver-fragment name="v3-auth-rules" %}}
-{{< rver-fragment name="v3-auth-rules" withVersioning=true >}}
 
 ## Unchanged from v2
 

content/rooms/v4.md

@@ -2,6 +2,7 @@
 title: Room Version 4
 type: docs
 weight: 40
+version: 4
 ---
 
 This room version builds on [version 3](/rooms/v3) using a different
@@ -46,7 +47,7 @@ being interpreted differently by some reverse proxy software, and
 generally made administration harder.
 {{% /boxes/rationale %}}
 
-{{% rver-fragment name="v4-event-ids" withVersioning="true" %}}
+{{% rver-fragment name="v4-event-ids" %}}
 
 ## Unchanged from v3