Merge branch 'main' into clarify-identifier-localparts

.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,19 +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)):
 
-* [ ] Blog post written
+* [ ] Pin this issue to the repo.
-* [ ] Check for release blockers that may have been missed
+* [ ] Ensure the social media account holders are available for the release day.
-* [ ] Review/fix the changelog
+* [ ] 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
+* [ ] 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/_typos.toml

@@ -10,3 +10,4 @@ au1ba7o = "au1ba7o"
 [default.extend-words]
 Appy = "Appy"
 fo = "fo"
+Iy = "Iy"

.github/pull_request_template.md

@@ -1,11 +1,3 @@
----
-name: Spec clarification/not a proposal
-about: A change that's not a spec proposal, such as a clarification to the spec itself.
-title: ''
-labels: ''
-assignees: ''
-
----
 
 ### Pull Request Checklist
 

.github/workflows/checks.yaml

@@ -10,7 +10,7 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - run: scripts/check-newsfragments

.github/workflows/main.yml

@@ -1,4 +1,8 @@
 name: "Spec"
+
+env:
+  HUGO_VERSION: 0.139.0
+
 on:
   push:
     branches:
@@ -18,23 +22,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
       - name: "🔎 Run validator"
         run: |
           npx @redocly/cli@latest lint data/api/*/*.yaml
 
-  check-examples:
+  check-event-examples:
     name: "🔎 Check Event schema examples"
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -45,7 +49,45 @@ jobs:
       - name: "🔎 Run validator"
         run: |
           python scripts/check-event-schema-examples.py
-        
+
+  check-openapi-examples:
+    name: "🔎 Check OpenAPI definitions examples"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-openapi-sources.py
+
+  check-schemas-examples:
+    name: "🔎 Check JSON Schemas inline examples"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-json-schemas.py
+
   calculate-baseurl:
     name: "⚙️ Calculate baseURL for later jobs"
     runs-on: ubuntu-latest
@@ -61,11 +103,11 @@ jobs:
         # the asterisk matching behaviour, not the literal string.
         run: |
           if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo ::set-output name=baseURL::/
+              echo "baseURL=/" >> "$GITHUB_OUTPUT"
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
+              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
           else
-              echo ::set-output name=baseURL::/unstable
+              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
           fi
 
   build-openapi:
@@ -74,9 +116,9 @@ jobs:
     needs: [calculate-baseurl]
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -92,24 +134,29 @@ jobs:
             export RELEASE="unstable"
           fi
           # The output path matches the final deployment path at spec.matrix.org
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.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 \
+          scripts/dump-openapi.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 \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api push-gateway \
             -r "$RELEASE" \
             -o spec/push-gateway-api/api.json
+          scripts/dump-openapi.py \
+              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
+              --api server-server \
+              -r "$RELEASE" \
+              -o spec/server-server-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: openapi-artifact
           path: openapi.tar.gz
@@ -121,18 +168,20 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
         run: ./scripts/generate-changelog.sh vUNSTABLE
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: changelog-artifact
-          path: content/changelog/vUNSTABLE.md
+          path: content/changelog/unstable.md
 
   build-spec:
     name: "📖 Build the spec"
@@ -142,23 +191,23 @@ jobs:
     if: ${{ always() }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.113.0'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           npm i
           npm run get-proposals
       - name: "📥 Download generated changelog"
         if: "needs.generate-changelog.result == 'success'"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: changelog-artifact
           path: content/changelog
@@ -169,7 +218,7 @@ jobs:
       # https://spec.matrix.org/latest/client-server-api/api.json
       # Works for /unstable/ and /v1.1/ as well.
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -179,7 +228,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: spec-artifact
           path: spec.tar.gz
@@ -190,10 +239,10 @@ jobs:
     needs: [calculate-baseurl, build-spec]
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: "📥 Fetch built spec"
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v4
         with:
           name: spec-artifact
 
@@ -210,7 +259,7 @@ jobs:
       - name: "Run htmltest"
         uses: wjdp/htmltest-action@master
         with:
-          config: .htmltest.yaml
+          config: .htmltest.yml
 
   build-historical-spec:
     name: "📖 Build the historical backup spec"
@@ -219,16 +268,16 @@ jobs:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.93.3'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           npm i
@@ -240,7 +289,7 @@ jobs:
           hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -250,7 +299,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec-historical.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -25,17 +25,20 @@ 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" |
                jq -r '.[] | .number')
           echo "PR number: $pr_number"
-          echo "::set-output name=prnumber::$pr_number"
+          echo "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
         
       - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@af92a8455a59214b7b932932f2662fdefbd78126 # v2.15.0
+        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
         with:
           workflow: main.yaml
           run_id: ${{ github.event.workflow_run.id }}
@@ -46,8 +49,7 @@ jobs:
         
       - name: "📤 Deploy to Netlify"
         id: netlify
-        # v1.2.2
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
-        uses: nwtgck/actions-netlify@f517512ae75beec8896aa7b027c1c72f01816200
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -0,0 +1,42 @@
+name: Release packages
+on:
+  release:
+    types: [published]
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+jobs:
+  # Releases to npm after bumping the package.json version from 0.0.0 to $TAG.0 as the tags only contain MAJOR.MINOR
+  npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    if: github.event.release.prerelease == false
+    defaults:
+      run:
+        working-directory: packages/npm
+    steps:
+      - name: 🧮 Checkout code
+        uses: actions/checkout@v4
+
+      - name: 🔧 Yarn cache
+        uses: actions/setup-node@v4
+        with:
+          cache: "yarn"
+          cache-dependency-path: packages/npm/yarn.lock
+          registry-url: "https://registry.npmjs.org"
+
+      - name: 🔨 Install dependencies
+        run: "yarn install --frozen-lockfile"
+
+      # We bump the package.json version to git, we just need it for publish to do the right thing
+      - name: 🎖 Bump package.json version
+        run: "yarn version --new-version ${VERSION#v} --no-git-tag-version"
+        env:
+          VERSION: ${{ github.event.release.tag_name }}.0
+
+      - name: 🚀 Publish to npm
+        id: npm-publish
+        uses: JS-DevTools/npm-publish@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1
+        with:
+          token: ${{ secrets.NPM_TOKEN }}
+          package: packages/npm
+          access: public
+          ignore-scripts: false

.github/workflows/spell-check.yaml

@@ -11,9 +11,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Actions Repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@9be36f97fdbe645ee9a12449fb13aca856c2516a
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
       with:
-        config: ${{github.workspace}}/.github/_typos.toml
+        config: ${{github.workspace}}/.github/_typos.toml

.gitignore

@@ -2,7 +2,7 @@ node_modules
 /data/msc
 /env*
 /resources
-/scripts/swagger
+/scripts/openapi
 /scripts/tmp
 /hugo-config.toml
 /public
@@ -14,3 +14,4 @@ _rendered.rst
 /spec/
 changelogs/rendered.*
 .hugo_build.lock
+hugo_stats.json

.gitmodules

@@ -1,7 +0,0 @@
-[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

.htmltest.yml

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

CONTRIBUTING.rst

@@ -12,7 +12,7 @@ The documentation style is described at
 https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst.
 
 Matrix-spec workflows
---------------------
+---------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -72,7 +72,7 @@ ask.
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-All API specifications require a changelog entry. Adding to the changelog can only
+All changes to the contents of this repository require a changelog entry. Adding to the changelog can only
 be done after you've opened your pull request, so be sure to do that first.
 
 The changelog is managed by `Towncrier <https://github.com/twisted/towncrier>`_ in the
@@ -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.
@@ -117,7 +119,7 @@ license - in our case, this is Apache Software License v2 (see LICENSE).
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach used by the `Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_,
-`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md`_, and many other
+`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md>`_, and many other
 projects: the `Developer Certificate of Origin <http://developercertificate.org/>`_
 (DCO). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::
@@ -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

@@ -22,7 +22,7 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener
 
 * `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as
   [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and
-  parse them. This is also where our Swagger/OpenAPI definitions and schemas are.
+  parse them. This is also where our OpenAPI definitions and schemas are.
 
 * `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of
   a page: for example, whether it has header, footer, sidebar, and so on.
@@ -52,6 +52,7 @@ Additionally, the following directories may be of interest:
 * `/data-definitions`: Bits of structured data consumable by Matrix implementations.
 * `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
 * `/scripts`: Various scripts for generating the spec and validating its contents.
+* `/packages`: Various packages for shipping spec files like OpenAPI bindings and data definitions.
 
 ## Authoring changes to the spec
 
@@ -60,13 +61,12 @@ 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.93.0 is required.
+   v0.123.1 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
    to process the SCSS.)
-2. Run `npm i` to install the dependencies and fetch the docsy git submodule.
+2. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
-   Note that this will require NodeJS to be installed.
 3. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
    page and is not required.
 4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
@@ -86,13 +86,13 @@ steps for authoring changes to the specification and instead of `hugo serve` run
 spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"`
 to the `hugo -d "spec"` command.
 
-For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
+For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
-and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file,
+and finally `python ./scripts/dump-openapi.py` to generate it to `./scripts/openapi/api-docs.json`. To make use of the generated file,
 there are a number of options:
 
-* You can open `./scripts/swagger-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
+* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
-* You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation by
+* You can run a local HTTP server by running `./scripts/openapi-http-server.py`, and then view the documentation by
-  opening `./scripts/swagger-preview.html` in your browser.
+  opening `./scripts/openapi-preview.html` in your browser.
 
 ## Issue tracking
 

assets/css/fonts/Inter.css

@@ -0,0 +1,63 @@
+/* cyrillic-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-cyrillic-ext-normal.woff2) format('woff2');
+  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
+}
+/* cyrillic */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-cyrillic-normal.woff2) format('woff2');
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+/* greek-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-greek-ext-normal.woff2) format('woff2');
+  unicode-range: U+1F00-1FFF;
+}
+/* greek */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-greek-normal.woff2) format('woff2');
+  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
+}
+/* vietnamese */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-vietnamese-normal.woff2) format('woff2');
+  unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
+}
+/* latin-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-latin-ext-normal.woff2) format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-latin-normal.woff2) format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

assets/css/fonts/README.md

@@ -3,7 +3,7 @@
 ## Inter.css
 
 `Inter.css` is a local copy of
-https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i, modified to pull
+https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,100..900&display=swap, modified to pull
 font files (`.woff2`) from local sources. It was created
 using `download_google_fonts_css.py`.
   
@@ -15,9 +15,9 @@ load them. Example call:
 
 ```sh
 python3 download_google_fonts_css.py \
-  "https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i" \
+  "https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,100..900&display=swap" \
-  ../../fonts \
+  ../../../static/fonts \
-  ../../fonts 
+  ../../fonts
 ```
   
 Which would pop out a `Inter.css` file that should be `@import url("Inter.css")`d

assets/css/fonts/download_google_fonts_css.py

@@ -84,7 +84,6 @@ new_css_file_lines = []
 font_lang = None
 font_family = None
 font_style = None
-font_weight = 0
 for line in original_contents:
     # Check if this line contains a font URL
     match = re.match(r".*url\((.*)\) format.*", line)
@@ -96,16 +95,17 @@ for line in original_contents:
         resp = requests.get(font_url)
         if resp.status_code == 200:
             # Save the font file
-            filename = "%s-%s-%s-%d.woff2" % (
+            filename = "%s-%s-%s.woff2" % (
-                font_family, font_lang, font_style, font_weight
+                font_family, font_lang, font_style
             )
             font_filepath = font_output_dir + filename
             with open(font_filepath, "wb") as f:
                 print("Writing font file:", font_filepath)
                 f.write(resp.content)
 
-            # Replace google URL with local URL
+            # Replace google URL with local URL and allow the browser to load the
-            line = re.sub(r"url\(.+\)", f"url({css_font_path + filename})", line)
+            # local font if it exists.
+            line = re.sub(r"url\(.+?\)", f"local('{font_family}'), url({css_font_path + filename})", line)
         else:
             print("Warning: failed to download font file:", font_url)
 
@@ -121,9 +121,6 @@ for line in original_contents:
     font_style_match = re.match(r".*font-style: (.+);$", line)
     if font_style_match:
         font_style = font_style_match.group(1)
-    font_weight_match = re.match(r".*font-weight: (.+);$", line)
-    if font_weight_match:
-        font_weight = int(font_weight_match.group(1))
 
     # Append the potentially modified line to the new css file
     new_css_file_lines.append(line)

assets/diagrams/README.md

@@ -7,11 +7,17 @@ https://www.diagrams.net/ is a great ([open source](https://github.com/jgraph/dr
 tool for these sorts of things - include your `.drawio` file next to your diagram.
 
 Suggested settings for diagrams.net:
-* Export as PNG.
+* Export as WebP.
-* 100% size.
+* 200% size.
 * `20` for a border width.
-* No transparent background, shadow, or grid.
+* Light appearance.
-* Include a copy of the diagram.
+* No shadow, or grid.
 
-To reference a diagram, use the absolute path when compiled. For example,
+To reference a diagram, use the `diagram` shortcode. For example:
-`![membership-flow-diagram](/diagrams/membership.png)`
+
+```
+{{% diagram name="membership" alt="Diagram presenting the possible membership state transitions" %}}
+```
+
+Where `name` is the file name without extension, and `alt` is a textual
+replacement for the image, useful for accessibility.

assets/icons/favicon.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
+   <style>
+      path { fill: #000000; }
+      @media (prefers-color-scheme: dark) {
+          path { fill: #ffffff; }
+      }
+   </style>
+   <path d="M 30,2.0000001 V 30 h -1 -2 v 2 h 5 V -3.3333334e-8 L 27,0 v 2 z"/>
+   <path d="M 9.9515939,10.594002 V 12.138 h 0.043994 c 0.3845141,-0.563728 0.8932271,-1.031728 1.4869981,-1.368 0.580003,-0.322998 1.244999,-0.485 1.993002,-0.485 0.72,0 1.376999,0.139993 1.971998,0.42 0.595,0.279004 1.047001,0.771001 1.355002,1.477001 0.338003,-0.500001 0.795999,-0.941 1.376999,-1.323001 0.579999,-0.382998 1.265998,-0.574 2.059998,-0.574 0.602003,0 1.160002,0.074 1.674002,0.220006 0.514,0.148006 0.953998,0.382998 1.321999,0.706998 0.36601,0.322999 0.653001,0.746 0.859,1.268002 0.205001,0.521998 0.307994,1.15 0.307994,1.887001 v 7.632997 h -3.127 v -6.463997 c 0,-0.383002 -0.01512,-0.743002 -0.04399,-1.082003 -0.02079,-0.3072 -0.103219,-0.607113 -0.242003,-0.881998 -0.133153,-0.25081 -0.335962,-0.457777 -0.584001,-0.596002 -0.257008,-0.146003 -0.605998,-0.220006 -1.046997,-0.220006 -0.440002,0 -0.796003,0.085 -1.068,0.253002 -0.272013,0.170003 -0.485001,0.390002 -0.639001,0.662003 -0.159119,0.287282 -0.263585,0.601602 -0.307994,0.926997 -0.05197,0.346923 -0.07801,0.697217 -0.07801,1.048002 v 6.353999 h -3.128005 v -6.398 c 0,-0.338003 -0.0072,-0.673001 -0.02116,-1.004001 -0.01134,-0.313663 -0.07487,-0.623229 -0.187994,-0.915999 -0.107943,-0.276623 -0.300435,-0.512126 -0.550001,-0.673001 -0.25799,-0.168 -0.636,-0.253002 -1.134999,-0.253002 -0.198123,0.0083 -0.394383,0.04195 -0.584002,0.100006 -0.258368,0.07446 -0.498455,0.201827 -0.704999,0.373985 -0.227981,0.183987 -0.421999,0.449 -0.583997,0.794003 -0.161008,0.345978 -0.242003,0.797998 -0.242003,1.356998 v 6.618999 H 6.99942 V 10.590001 Z"/>
+   <path d="M 2,2.0000001 V 30 h 3 v 2 H 0 V 9.2650922e-8 L 5,0 v 2 z"/>
+</svg>

assets/js/toc.js

@@ -0,0 +1,169 @@
+/*
+Copyright 2020, 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/*
+  Only call the given function once every 250 milliseconds to avoid impacting
+  the performance of the browser.
+  Source: https://remysharp.com/2010/07/21/throttling-function-calls
+*/
+function throttle(fn) {
+  const threshold = 250;
+  let last = null;
+  let deferTimer = null;
+
+  return function (...args) {
+    const now = new Date();
+
+    if (last && now < last + threshold) {
+      // Hold on to it.
+      clearTimeout(deferTimer);
+      deferTimer = setTimeout(() => {
+        last = now;
+        fn.apply(this, args);
+      }, threshold);
+    } else {
+      last = now;
+      fn.apply(this, args);
+    }
+  }
+}
+
+/*
+  Get the list of headings that appear in the ToC.
+  This is not as simple as querying all the headings in the content, because
+  some headings are not rendered in the ToC (e.g. in the endpoint definitions).
+*/
+function getHeadings() {
+  let headings = [];
+
+  // First get the anchors in the ToC.
+  const toc_anchors = document.querySelectorAll("#toc nav a");
+
+  for (const anchor of toc_anchors) {
+    // Then get the heading from its selector in the anchor's href.
+    const selector = anchor.getAttribute("href");
+    if (!selector) {
+      console.error("Got ToC anchor without href");
+      continue;
+    }
+    
+    const heading = document.querySelector(selector);
+    if (!heading) {
+      console.error("Heading not found for selector:", selector);
+      continue;
+    }
+
+    headings.push(heading);
+  }
+
+  return headings;
+}
+
+/*
+  Get the heading of the text visible at the top of the viewport.
+  This is the first heading above or at the top of the viewport.
+*/
+function getCurrentHeading(headings, headerOffset) {
+  const scrollTop = document.documentElement.scrollTop;
+  let prevHeading = null;
+  let currentHeading = null;
+  let index = 0;
+
+  for (const heading of headings) {
+    // Compute the position compared to the viewport.
+    const rect = heading.getBoundingClientRect();
+
+    if (rect.top >= headerOffset && rect.top <= headerOffset + 30) {
+      // This heading is at the top of the viewport, this is the current heading.
+      currentHeading = heading;
+      break;
+    }
+    if (rect.top >= headerOffset) {
+      // This is in or below the viewport, the current heading should be the
+      // previous one.
+      if (prevHeading) {
+        currentHeading = prevHeading;
+      } else {
+        // The first heading does not have a prevHeading.
+        currentHeading = heading;
+      }
+      break;
+    }
+
+    prevHeading = heading;
+    index += 1;
+  }
+
+  // At the bottom of the page we might not have a heading.
+  if (!currentHeading) {
+    currentHeading = prevHeading;
+  }
+
+  return currentHeading;
+}
+
+/*
+  Select the ToC entry that points to the given ID.
+  Clear any previously highlighted ToC items, select the new one,
+  and adjust the ToC scroll position.
+*/
+function selectTocEntry(id) {
+  // Deselect previously selected entries.
+  const activeEntries = document.querySelectorAll("#toc nav a.active");
+  for (const activeEntry of activeEntries) {
+    activeEntry.classList.remove('active');
+  }
+
+  // Find the new entry and select it.
+  const newEntry = document.querySelector(`#toc nav a[href="#${id}"]`);
+  if (!newEntry) {
+    console.error("ToC entry not found for ID:", id);
+    return;
+  }
+  newEntry.classList.add('active');
+
+  // Don't scroll the sidebar nav if the main content is not scrolled
+  const nav = document.querySelector("#td-section-nav");
+  const content = document.querySelector("html");
+  if (content.scrollTop !== 0) {
+    nav.scrollTop = newEntry.offsetTop - 100;
+  } else {
+    nav.scrollTop = 0;
+  }
+}
+
+/*
+  Track when the view is scrolled, and use this to update the highlight for the
+  corresponding ToC entry.
+*/
+window.addEventListener('DOMContentLoaded', () => {
+  // Part of the viewport is below the header so we should take it into account.
+  const headerOffset = document.querySelector("body > header > nav").clientHeight;
+  const headings = getHeadings();
+
+  const onScroll = throttle((_e) => {
+    // Update the ToC.
+    let heading = getCurrentHeading(headings, headerOffset);
+    selectTocEntry(heading.id);
+  });
+
+  // Initialize the state of the ToC.
+  onScroll();
+
+  // Listen to scroll and resizing changes.
+  document.addEventListener('scroll', onScroll, false);
+  document.addEventListener('resize', onScroll, false);
+});

assets/scss/_styles_project.scss

@@ -18,9 +18,6 @@ limitations under the License.
 Custom SCSS for the Matrix spec
 */
 
-@import "variables_project";
-@import "variables";
-
 /* Import the CSS classes for the syntax highlighter.
  *
  * This is generated with:
@@ -29,12 +26,6 @@ Custom SCSS for the Matrix spec
  */
 @import "syntax.scss";
 
-/* Workaround for https://github.com/google/docsy/issues/1116:
- * fix scroll-anchoring */
-.td-outer {
-    height: auto;
-}
-
 /* Overrides for the navbar */
 .td-navbar {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
@@ -43,10 +34,17 @@ Custom SCSS for the Matrix spec
   .navbar-brand {
     font-size: 1.1rem;
 
+    /* Allow the text to wrap if it is wider than the viewport */
+    text-align: center;
+    white-space: normal;
+
     .navbar-version {
       color: $secondary;
     }
+  }
 
+  .nav-link {
+    font-weight: normal;
   }
 
   a {
@@ -114,7 +112,7 @@ Custom SCSS for the Matrix spec
   }
 }
 
-@media (min-width: 768px) {
+@include media-breakpoint-up(md) {
   @supports (position: sticky) {
     .td-sidebar-nav {
       /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */
@@ -124,8 +122,11 @@ Custom SCSS for the Matrix spec
 }
 
 /* Customise footer */
-footer {
+.td-footer {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
+  padding-top: 2rem;
+  color: var(--bs-body-color);
+  background-color: var(--bs-body-color-bg);
 }
 
 /* Auto numbering for headings */
@@ -171,6 +172,13 @@ footer {
 
 }
 
+/* Remove some padding before the main content, when the sidebar is disabled */
+.td-main main {
+  @include media-breakpoint-down(md) {
+    padding-top: 0;
+  }
+}
+
 /* Adjust the scroll margin for everything in the main content, so that
  * it doesn't disappear behind the header bar */
 .td-content * {
@@ -266,33 +274,10 @@ footer {
     border-left-width: 5px;
     background: $warning-background;
   }
-
-  // XXX: See the added-in-paragraph.html shortcode for more information on these styles.
-  &.added-in-paragraph {
-    // Remove the padding and margin to remove the box look
-    margin: 0 !important; // !important on both to override table-related rules
-    padding: 0 !important;
-
-    // Make pairs of "added-in" and content inline to each other. We do pairs so authors can
-    // describe two paragraphs with added-in prefixes within a single box, reducing DOM
-    // complexity. Each paragraph is expected to be prefixed with an added-in, however.
-    //
-    // XXX: We assume the added-in and text will be rendered as paragraph elements.
-    > p {
-      display: inline;
-    }
-    > p:nth-child(2n) { // "even" rule to target just the content paragraphs
-      // Force a paragraph break after the content (insert a couple <br /> tags)
-      &::after {
-        content: '\A\A';
-        white-space: pre;
-      }
-    }
-  }
 }
 
 /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
-.rendered-data {
+.td-content .rendered-data {
   background-color: $secondary-lightest-background;
   padding: 0.85rem;
   margin: 0.85rem 0;
@@ -346,7 +331,7 @@ footer {
   }
 
   p code, table code {
-    background-color: inherit;
+    background-color: transparent;
   }
 
   table {
@@ -396,6 +381,12 @@ footer {
 
     th, td, caption {
       padding: 1rem;
+      border-top: 1px $table-border-color solid;
+    }
+
+    td > p:last-child {
+      // Avoid unnecessary space at the bottom of the cells.
+      margin-bottom: 0;
     }
 
     &.object-table, &.response-table, &.content-type-table {
@@ -408,14 +399,12 @@ footer {
 
             // ... but avoid double border between caption and table
             border-bottom: 0;
+
+            background-color: $secondary-lighter-background;
         }
 
-        caption, tbody tr {
+        tbody tr {
-            background-color: $table-row-default;
+            --bs-table-striped-bg: #{$secondary-lighter-background};
-        }
-
-        tbody tr:nth-child(even) {
-            background-color: $table-row-alternate;
         }
     }
 
@@ -427,6 +416,31 @@ footer {
     &.basic-info th {
       width: 15rem;
     }
+
+    /* Arrange rows vertically when horizontal space is constrained to avoid overflowing */
+    @include media-breakpoint-down(sm) {
+      /* Make cells full width without vertical margin */
+      &.basic-info th, &.basic-info td {
+        width: 100%;
+        display: inline-block;
+        margin-top: 0;
+        margin-bottom: 0;
+      }
+
+      /* Remove border and padding between header & data cells to make them appear like a single cell */
+      &.basic-info td {
+        padding-top: 0;
+        border-top: none;
+      }
+      &.basic-info th {
+        border-bottom: none;
+      }
+
+      /* Remove top border on all but the first header cell to prevent double borders between rows */
+      &.basic-info tr + tr th {
+        border-top: none;
+      }
+    }
   }
 
   pre {
@@ -471,12 +485,18 @@ of .td-content. This applies the same style to any blockquotes that descend from
 Make padding symmetrical (this selector is used in the default styles to apply padding-left: 3rem)
 */
 .pl-md-5, .px-md-5 {
-  padding-right: 3rem;
+  @include media-breakpoint-up(md) {
+    padding-right: 3rem;
+  }
 }
 
 /* Adjust default styles for info banner */
 .pageinfo-primary {
-  max-width: 80%;
+  @include media-breakpoint-up(lg) {
+    max-width: 80%;
+  }
+  margin-top: 0;
+  margin-right: 0;
   margin-left: 0;
   border: 0;
   border-left: solid 5px $secondary;
@@ -517,3 +537,15 @@ dd {
     border-radius: 0.25rem;  // was $border-radius, but that var isn't accessible here.
   }
 }
+
+/* Style for breadcrumbs */
+.td-breadcrumbs {
+  padding: .75rem 1rem;
+  background-color: #eee;
+  border-radius: .25rem;
+  margin-bottom: 1rem;
+
+  .breadcrumb {
+    margin: 0;
+  }
+}

assets/scss/_variables_project.scss

@@ -20,7 +20,7 @@ $dark: #333;
 $gray-100: #FBFBFB;
 
 $secondary-background: #E5F5FB;
-$secondary-lighter-background: #F4FaFC;
+$secondary-lighter-background: #F4FAFC;
 $secondary-lightest-background: #FBFDFD;
 
 
@@ -33,20 +33,24 @@ $warning-background: #FFE0E0;
 // colours for definition tables.
 // the border colour matches that used for "highlight" divs
 $table-border-color: rgba(black, .125);
-$table-row-alternate: $secondary-lightest-background;
+$table-bg: $secondary-lightest-background;
-$table-row-default: $secondary-lighter-background;
 
 /* Configure docsy to use the default system fonts instead of Google Fonts.
  * See https://www.docsy.dev/docs/adding-content/lookandfeel/#fonts */
 $td-enable-google-fonts: false;
 
 /*
- * Replace the default font with Inter.
+ * The $font-family-sans-serif definition here overrides the default value set by docsy
- *
+ * (https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68)
- * The $font-family-sans-serif definition here overrides the default value set by docsy:
- * https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68
- * and adds "Inter" to the front.
- *
- * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html.
  */
-$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+$font-family-sans-serif:
+  // Add "Inter" to the front, making it the default. The font itself is loaded via stylesheet
+  // links in layouts/partials/hooks/head-end.html.
+  "Inter",
+  -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
+  // Insert fonts suited for mathematical symbols on different platforms before "Arial"
+  "STIX Two Math", "Cambria Math", "Noto Sans Math", "Dejavu Sans",
+  Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+
+// Disable smooth scrolling as it makes TOC highlighting jump during the transition.
+$enable-smooth-scroll: false;

changelogs/appendices/newsfragments/1573.clarification

@@ -1 +0,0 @@
-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

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

changelogs/application_service/newsfragments/1584.clarification

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

changelogs/client_server/newsfragments/1552.clarification

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

changelogs/client_server/newsfragments/1563.clarification

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

changelogs/client_server/newsfragments/1564.clarification

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

changelogs/client_server/newsfragments/1578.clarification

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

changelogs/client_server/newsfragments/1579.clarification

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

changelogs/client_server/newsfragments/1585.clarification

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

changelogs/client_server/newsfragments/1590.clarification

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

changelogs/client_server/newsfragments/1593.clarification

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

changelogs/client_server/newsfragments/1597.clarification

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

changelogs/client_server/newsfragments/2038.clarification

@@ -0,0 +1 @@
+Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.

changelogs/header.md

@@ -1,16 +0,0 @@
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    VERSION  = Replaced by the version number (eg: v1.2)
-    DATE     = Replaced by the date (eg: April 01, 2021)
--->
-
-## VERSION
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/VERSION">https://github.com/matrix-org/matrix-spec/tree/VERSION</a></td>
-<tr><th>Release date</th><td>DATE</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

changelogs/identity_service/newsfragments/1563.clarification

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

changelogs/internal/newsfragments/1310.feature

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

changelogs/internal/newsfragments/1542.clarification

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

changelogs/internal/newsfragments/1549.clarification

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

changelogs/internal/newsfragments/1551.clarification

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

changelogs/internal/newsfragments/1556.clarification

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

changelogs/internal/newsfragments/1558.clarification

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

changelogs/internal/newsfragments/1561.clarification

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

changelogs/internal/newsfragments/1562.clarification

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

changelogs/internal/newsfragments/1582.clarification

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

changelogs/internal/newsfragments/1591.clarification

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

changelogs/internal/newsfragments/1598.clarification

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

changelogs/internal/newsfragments/1601.clarification

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

changelogs/internal/newsfragments/2033.clarification

@@ -0,0 +1 @@
+Generate the changelog release info with Hugo, rather than the changelog generation script.

changelogs/internal/newsfragments/2041.clarification

@@ -0,0 +1 @@
+Update release steps documentation.

changelogs/server_server/newsfragments/1521.clarification

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

changelogs/server_server/newsfragments/1559.clarification

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

changelogs/server_server/newsfragments/1560.clarification

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

changelogs/server_server/newsfragments/1563.clarification

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

changelogs/server_server/newsfragments/1564.clarification

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

changelogs/server_server/newsfragments/1578.clarification

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

changelogs/template.md.jinja

@@ -1,7 +1,7 @@
 {% for section_name, section in sections.items() %}
 {% if section_name %}
 
-### {{section_name}}
+## {{section_name}}
 {% endif %}
 
 {% if section %}

config/_default/hugo.toml

@@ -1,29 +1,44 @@
+# Default settings.
+
 baseURL = "/"
 title = "Matrix Specification"
 
-# Prepends absolute URLs with the baseURL. Useful when hosting on non-root
-# paths, such as /unstable.
-canonifyURLs = true
-
 enableRobotsTXT = true
 
-# Hugo allows theme composition (and inheritance). The precedence is from left to right.
-theme = ["docsy"]
-
 # We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
 # links to it when used with a --baseURL (for example, https://spec.matrix.org/v1.4/
 # contains `<link rel="alternate" type="application/rss&#43;xml" href="/v1.4/v1.4/index.xml">`).
-disableKinds = ["taxonomy", "taxonomyTerm", "RSS"]
+disableKinds = ["taxonomy", "RSS"]
 
 [languages]
 [languages.en]
 title = "Matrix Specification"
-description = "Home of the Matrix specification for decentralised communication"
 languageName ="English"
 # Weight used for sorting.
 weight = 1
+[languages.en.params]
+description = "Home of the Matrix specification for decentralised communication"
+
+# Entries in the main menu in the header.
+[menus]
+[[menus.main]]
+    name = 'Foundation'
+    url = 'https://matrix.org/foundation/'
+    weight = 10
+[[menus.main]]
+    name = 'FAQs'
+    url = 'https://matrix.org/faq'
+    weight = 20
+[[menus.main]]
+    name = 'Blog'
+    url = 'https://matrix.org/blog/posts'
+    weight = 30
 
 [markup]
+  [markup.tableOfContents]
+    startLevel = 2
+    endLevel = 6
+    ordered = true
   [markup.goldmark]
     [markup.goldmark.renderer]
       # Enables us to render raw HTML
@@ -42,7 +57,6 @@ weight = 1
 
 [params]
 copyright = "The Matrix.org Foundation CIC"
-privacy_policy = "https://matrix.org/legal/privacy-notice"
 
 [params.version]
 # must be one of "unstable", "current", "historical"
@@ -53,13 +67,11 @@ 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 = "7"
+# minor = "13"
-# release_date = "May 25, 2023"
+# release_date = "December 19, 2024"
 
 # User interface configuration
 [params.ui]
-# Set to true to disable the About link in the site footer
-footer_about_disable = false
 # Collapse HTTP API and event <details> elements
 rendered_data_collapsed = false
 # Hide the search entry in the sidebar
@@ -75,22 +87,28 @@ sidebar_menu_compact = true
 # 	icon = "fa fa-envelope"
 #         desc = "Discussion and help from your fellow users"
 # Developer relevant links. These will show up on right side of footer and in the community page if you have one.
-[[params.links.developer]]
+# [[params.links.developer]]
+# 	name = "GitHub"
+# 	url = "https://github.com/matrix-org"
+# 	icon = "fab fa-github"
+#   desc = "Matrix on GitHub"
+# Custom links shown in the center of the footer. (Only supported by our fork of docsy's 'footer/central' partial.)
+[[params.links.bottom]]
 	name = "GitHub"
 	url = "https://github.com/matrix-org"
 	icon = "fab fa-github"
   desc = "Matrix on GitHub"
-[[params.links.developer]]
+[[params.links.bottom]]
 	name = "GitLab"
 	url = "https://gitlab.matrix.org/matrix-org"
 	icon = "fab fa-gitlab"
   desc = "Matrix on GitLab"
-[[params.links.developer]]
+[[params.links.bottom]]
 	name = "YouTube"
 	url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
 	icon = "fab fa-youtube"
   desc = "Matrix YouTube channel"
-[[params.links.developer]]
+[[params.links.bottom]]
 	name = "Twitter"
 	url = "https://twitter.com/matrixdotorg"
 	icon = "fab fa-twitter"
@@ -111,3 +129,21 @@ sidebar_menu_compact = true
     X-Frame-Options = "sameorigin"
     Access-Control-Allow-Origin = "*"
     Access-Control-Allow-Methods = "GET"
+
+# hugo module configuration
+
+[module]
+  [module.hugoVersion]
+    extended = true
+    min = "0.123.1"
+  [[module.imports]]
+    path = "github.com/matrix-org/docsy"
+    disable = false
+
+# custom output formats
+
+[outputFormats]
+  [outputFormats.Checklist]
+    mediaType = "text/markdown"
+    isPlainText = true
+    baseName = "checklist"

config/production/hugo.toml

@@ -0,0 +1,6 @@
+# Settings only required when the website is built for production.
+
+# Enable stats to use them to optimize the CSS.
+[build]
+  [build.buildStats]
+    enable = true

content/_index.md

@@ -56,9 +56,6 @@ The principles that Matrix attempts to follow are:
         the global Matrix network
     -   Fully open standard - publicly documented standard with no IP or
         patent licensing encumbrances
-    -   Fully open source reference implementation - liberally-licensed
-        example implementations with no IP or patent licensing
-        encumbrances
 -   Empowering the end-user
     -   The user should be able to choose the server and clients they
         use
@@ -99,6 +96,20 @@ services - be that for instant messages, VoIP call setups, or any other
 objects that need to be reliably and persistently pushed from A to B in
 an interoperable and federated manner.
 
+### Requirement levels
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" across all parts of the
+specification are to be interpreted as described in
+[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+Some entire sections of the specification might be optional depending on the
+circumstances. For example, the
+[modules of the client-server API](/client-server-api/#modules)
+apply depending on the use case. The requirement level expressed by the above
+key words appearing in such a section is only relevant if the section itself is
+applicable.
+
 ### Spec Change Proposals
 
 To propose a change to the Matrix Spec, see the explanations at
@@ -419,9 +430,16 @@ into the `m.` namespace.
 
 ### Timestamps
 
-Unless otherwise stated, timestamps are measured as milliseconds since
+Unless otherwise stated, timestamps are the number of milliseconds
-the Unix epoch. Throughout the specification this may be referred to as
+elapsed since the unix epoch (1970-01-01 00:00:00 UTC), but not counting
-POSIX, Unix, or just "time in milliseconds".
+leap seconds, so that each day is precisely 86,400,000 milliseconds.
+
+This means that timestamps can repeat during leap seconds. Most
+programming languages provide timestamps in that format natively, e.g.
+[ECMAScript](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-time-values-and-time-range).
+Throughout the specification this may be referred to as POSIX,
+[Unix](https://en.wikipedia.org/wiki/Unix_time), or just "time in
+milliseconds".
 
 ## Specification Versions
 

content/appendices.md

@@ -136,12 +136,12 @@ removing insignificant whitespace, fractions, exponents and redundant
 character escapes.
 
     value     = false / null / true / object / array / number / string
-    false     = %x66.61.6c.73.65
+    false     = %x66.61.6C.73.65
-    null      = %x6e.75.6c.6c
+    null      = %x6E.75.6C.6C
     true      = %x74.72.75.65
-    object    = %x7B [ member *( %x2C member ) ] %7D
+    object    = %x7B [ member *( %x2C member ) ] %x7D
     member    = string %x3A value
-    array     = %x5B [ value *( %x2C value ) ] %5B
+    array     = %x5B [ value *( %x2C value ) ] %x5D
     number    = [ %x2D ] int
     int       = %x30 / ( %x31-39 *digit )
     digit     = %x30-39
@@ -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:
 
@@ -677,6 +677,9 @@ unicode codepoints, including control characters, except `:` and `NUL`
 (U+0000), but it is recommended to only include ASCII letters and
 digits (`A-Z`, `a-z`, `0-9`) when generating them.
 
+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:
@@ -690,8 +693,8 @@ homeserver to look up the alias.
 The localpart of a room alias may contain any valid unicode codepoints
 except `:`.
 
-Room aliases MUST NOT exceed 255 bytes as UTF-8 (including the `#` sigil
+The length of a room alias, including the `#` sigil and the domain, MUST
-and the domain).
+NOT exceed 255 bytes.
 
 #### Event IDs
 
@@ -703,10 +706,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
@@ -762,7 +767,7 @@ Specifically, the following mappings are used:
 * `r` for room aliases.
 * `u` for users.
 * `roomid` for room IDs (note the distinction from room aliases).
-* `e` for events, when after a room reference (`r` or `roomid`).
+* `e` for events, when after a room ID (`roomid`). Use of `e` after a room alias (`r`) is deprecated.
 
 {{% boxes/note %}}
 During development of this URI format, types of `user`, `room`, and `event`
@@ -772,6 +777,13 @@ wish to consider handling them as `u`, `r`, and `e` respectively.
 `roomid` was otherwise unchanged.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+{{% changed-in v="1.11" %}}
+Referencing event IDs within a room identified by room alias (`r`) rather than room ID
+(`roomid`) is now deprecated.  We are not aware of these ever having been used in
+practice, and are nonsensical given room aliases are mutable.
+{{% /boxes/note %}}
+
 The `id without sigil` is simply the identifier for the entity without the defined
 sigil. For example, `!room:example.org` becomes `room:example.org` (`!` is the sigil
 for room IDs). The sigils are described under the
@@ -816,7 +828,6 @@ Examples of common URIs are:
 <!-- Author's note: These examples should be consistent with the matrix.to counterparts. -->
 * Link to `#somewhere:example.org`: `matrix:r/somewhere:example.org`
 * Link to `!somewhere:example.org`: `matrix:roomid/somewhere:example.org?via=elsewhere.ca`
-* Link to `$event` in `#somewhere:example.org`: `matrix:r/somewhere:example.org/e/event`
 * Link to `$event` in `!somewhere:example.org`: `matrix:roomid/somewhere:example.org/e/event?via=elsewhere.ca`
 * Link to chat with `@alice:example.org`: `matrix:u/alice:example.org?action=chat`
 
@@ -826,9 +837,9 @@ A suggested client implementation algorithm is available in the
 #### matrix.to navigation
 
 {{% boxes/note %}}
-This namespacing existed prior to a `matrix:` scheme. This is **not**
+matrix.to is a Namespace URI which existed prior to a `matrix:` URI scheme.
-meant to be interpreted as an available web service - see below for more
+This is **not** meant to be interpreted as an available web service - see
-details.
+below for more details.
 {{% /boxes/note %}}
 
 A matrix.to URI has the following format, based upon the specification
@@ -860,10 +871,16 @@ Examples of matrix.to URIs are:
 <!-- Author's note: These examples should be consistent with the matrix scheme counterparts. -->
 * Link to `#somewhere:example.org`: `https://matrix.to/#/%23somewhere%3Aexample.org`
 * Link to `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org?via=elsewhere.ca`
-* Link to `$event` in `#somewhere:example.org`: `https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org`
 * Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca`
 * Link to `@alice:example.org`: `https://matrix.to/#/%40alice%3Aexample.org`
 
+{{% boxes/note %}}
+{{% changed-in v="1.11" %}}
+Referencing event IDs within a room identified by room alias rather than room ID
+is now deprecated.  We are not aware of these ever having been used in
+practice, and are nonsensical given room aliases are mutable.
+{{% /boxes/note %}}
+
 {{% boxes/note %}}
 Historically, clients have not produced URIs which are fully encoded.
 Clients should try to interpret these cases to the best of their
@@ -938,6 +955,50 @@ unique servers based on the following criteria:
     specify the servers it can. For example, a room with only 2 users in
     it would result in maximum 2 `via` parameters.
 
+### Opaque Identifiers
+
+The specification defines some identifiers to use the *Opaque Identifier
+Grammar*. This is a common grammar intended for non-user-visible identifiers
+which do not require parsing or interpretation (other than as a unique
+identifier).
+
+The grammar is defined as:
+
+* Identifiers must be entirely composed of the characters `[0-9]`, `[A-Z]`,
+  `[a-z]`, `-`, `.`, `_`, and `~`.
+* Unless otherwise specified, identifiers must be at least one character and at
+  most 255 characters in length.
+
+{{% boxes/note %}}
+The acceptable character set matches the unreserved character set in [RFC
+3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
+{{% /boxes/note %}}
+
+## Cryptographic key representation
+
+Sometimes it is necessary to present a private cryptographic key in the user
+interface.
+
+When this happens, the key SHOULD be presented as a string formatted as
+follows:
+
+1.  A byte array is created, consisting of two bytes `0x8B` and `0x01`,
+    followed by the raw key.
+2.  All the bytes in the array above, including the two header bytes,
+    are XORed together to form a parity byte. This parity byte is
+    appended to the byte array.
+3.  The byte array is encoded using base58, using the the alphabet
+    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
+4.  A space is added after every 4th character.
+
+When reading in a key, clients should disregard whitespace, and
+perform the reverse of steps 1 through 4.
+
+{{% boxes/note %}}
+The base58 alphabet is the same as that used for [Bitcoin
+addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart).
+{{% /boxes/note %}}
+
 ## 3PID Types
 
 Third-party Identifiers (3PIDs) represent identifiers on other

content/application-service-api.md

@@ -207,6 +207,39 @@ processed the events.
 
 {{% http-api spec="application-service" api="transactions" %}}
 
+##### Pushing ephemeral data
+
+{{% added-in v="1.13" %}}
+
+If the `receive_ephemeral` settings is enabled in the [registration](#registration)
+file, homeservers MUST send ephemeral data that is relevant to the application
+service via the transaction API, using the `ephemeral` property of the request's
+body. This property is an array that is effectively a combination of the
+`presence` and `ephemeral` sections of the client-server [`/sync`](/client-server-api/#get_matrixclientv3sync)
+API.
+
+There are currently three event types that can be delivered to an application
+service:
+
+- **[`m.presence`](/client-server-api/#mpresence)**: MUST be sent to the
+application service if the data would apply contextually. For example, a
+presence update for a user an application service shares a room with, or
+matching one of the application service's namespaces.
+- **[`m.typing`](/client-server-api/#mtyping)**: MUST be sent to the application
+service under the same rules as regular events, meaning that the application
+service must have registered interest in the room itself, or in a user that is
+in the room. The data MUST use the same format as the client-server API, with
+the addition of a `room_id` property at the top level to identify the room that
+they were sent in.
+- **[`m.receipt`](/client-server-api/#mreceipt)**: MUST be sent to the
+application service under the same rules as regular events, meaning that the
+application service must have registered interest in the room itself, or in a
+user that is in the room. The data MUST use the same format as the client-server
+API, with the addition of a `room_id` property at the top level to identify the
+room that they were sent in. [Private read receipts](/client-server-api/#private-read-receipts)
+MUST only be sent for users matching one of the application service's
+namespaces. Normal read receipts and threaded read receipts are always sent.
+
 #### Pinging
 
 {{% added-in v="1.7" %}}
@@ -436,6 +469,12 @@ 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`.
 
+If `/register` or `/login` is called with the `m.login.application_service`
+login type, but without a valid `as_token`, the endpoints will return an error
+with the `M_MISSING_TOKEN` or `M_UNKNOWN_TOKEN` error code and 401 as the HTTP
+status code. This is the same behavior as invalid auth in the client-server API
+(see [Using access tokens](/client-server-api/#using-access-tokens)).
+
 #### Pinging
 
 {{% added-in v="1.7" %}}

content/changelog/_index.md

@@ -0,0 +1,7 @@
+---
+title: Changelog
+type: docs
+weight: 1000
+---
+
+<!-- This page will be redirected to the latest version's changelog -->

content/changelog/historical.md

@@ -1,18 +1,15 @@
 ---
-title: Changelog
+title: Historical versions
 type: docs
-weight: 1000
+outputs:
+  - html
 ---
 
-{{% changelog/changelog-description %}}
+Before version 1.1, versioning was applied at the level of individual API specifications.
+This section includes links to these versions of the APIs.
 
-{{% changelog/changelogs %}}
+## Client-Server API
 
-<h2 id="historical-versions" class="no-numbers">Historical versions</h2>
-
-Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs.
-
-* **Client-Server API**
   -   [r0.6.1](https://matrix.org/docs/spec/client_server/r0.6.1.html)
   -   [r0.6.0](https://matrix.org/docs/spec/client_server/r0.6.0.html)
   -   [r0.5.0](https://matrix.org/docs/spec/client_server/r0.5.0.html)
@@ -26,22 +23,26 @@ Before version 1.1, versioning was applied at the level of individual API specif
       The last draft before the spec was formally released in version
       r0.0.0.
 
-* **Server-Server API**
+## Server-Server API
+
   -   [r0.1.4](https://matrix.org/docs/spec/server_server/r0.1.4.html)
   -   [r0.1.3](https://matrix.org/docs/spec/server_server/r0.1.3.html)
   -   [r0.1.2](https://matrix.org/docs/spec/server_server/r0.1.2.html)
   -   [r0.1.1](https://matrix.org/docs/spec/server_server/r0.1.1.html)
   -   [r0.1.0](https://matrix.org/docs/spec/server_server/r0.1.0.html)
 
-* **Application Service API**
+## Application Service API
+
   -   [r0.1.1](https://matrix.org/docs/spec/application_service/r0.1.1.html)
   -   [r0.1.0](https://matrix.org/docs/spec/application_service/r0.1.0.html)
 
-* **Identity Service API**
+## Identity Service API
+
   -   [r0.3.0](https://matrix.org/docs/spec/identity_service/r0.3.0.html)
   -   [r0.2.1](https://matrix.org/docs/spec/identity_service/r0.2.1.html)
   -   [r0.2.0](https://matrix.org/docs/spec/identity_service/r0.2.0.html)
   -   [r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html)
 
-* **Push Gateway API**
+## Push Gateway API
+
   -   [r0.1.0](https://matrix.org/docs/spec/push_gateway/r0.1.0.html)

content/changelog/v1.1.md

@@ -1,23 +1,15 @@
 ---
-date: 2021-11-09T00:00:00+0000
+title: v1.1 Changelog
+linkTitle: v1.1
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2021-11-09
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
+## Client-Server API
-    v1.1  = Replaced by the version number (eg: v1.2)
-    November 09, 2021     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.1
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.1">https://github.com/matrix-org/matrix-doc/tree/v1.1</a></td>
-<tr><th>Release date</th><td>November 09, 2021</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
 
 
 <strong>Breaking Changes</strong>
@@ -110,7 +102,7 @@ Variables:
 - Fix documentation errors around `threepid_creds`. ([#3471](https://github.com/matrix-org/matrix-doc/issues/3471))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>New Endpoints</strong>
@@ -136,7 +128,7 @@ Variables:
 - Tweak the example PDU diagram to better demonstrate situations with multiple `prev_events`. ([#3340](https://github.com/matrix-org/matrix-doc/issues/3340))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -145,7 +137,7 @@ Variables:
 - Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>New Endpoints</strong>
@@ -168,7 +160,7 @@ Variables:
 - Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. ([#3459](https://github.com/matrix-org/matrix-doc/issues/3459))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Spec Clarifications</strong>

content/changelog/v1.10.md

@@ -0,0 +1,93 @@
+---
+title: v1.10 Changelog
+linkTitle: v1.10
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-03-22
+---
+
+## Client-Server API
+
+**Backwards Compatible Changes**
+
+- Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026). ([#1728](https://github.com/matrix-org/matrix-spec/issues/1728))
+- Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025). ([#1730](https://github.com/matrix-org/matrix-spec/issues/1730))
+- Use the `body` field as optional media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530). ([#1731](https://github.com/matrix-org/matrix-spec/issues/1731))
+- Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929). ([#1733](https://github.com/matrix-org/matrix-spec/issues/1733))
+- Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077). ([#1735](https://github.com/matrix-org/matrix-spec/issues/1735))
+- Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041). ([#1737](https://github.com/matrix-org/matrix-spec/issues/1737))
+- Add support for recursion on the `GET /relations` endpoints, as per [MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981). ([#1746](https://github.com/matrix-org/matrix-spec/issues/1746))
+
+**Spec Clarifications**
+
+- The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead. ([#1629](https://github.com/matrix-org/matrix-spec/issues/1629))
+- Clarify that read receipts should be batched by thread as well as by room. ([#1685](https://github.com/matrix-org/matrix-spec/issues/1685))
+- Clarify that threads can be created based on replies. ([#1687](https://github.com/matrix-org/matrix-spec/issues/1687))
+- Clarify in the reply fallbacks example that the prefix sequence should be repeated for each line. ([#1690](https://github.com/matrix-org/matrix-spec/issues/1690))
+- Clarify the format of account data objects for secret storage. ([#1695](https://github.com/matrix-org/matrix-spec/issues/1695), [#1734](https://github.com/matrix-org/matrix-spec/issues/1734))
+- Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. ([#1712](https://github.com/matrix-org/matrix-spec/issues/1712))
+- Clarify one-time key and fallback key types in examples. ([#1715](https://github.com/matrix-org/matrix-spec/issues/1715))
+- Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes. ([#1719](https://github.com/matrix-org/matrix-spec/issues/1719))
+- Clarify how to perform the ECDH exchange in step 12 of the SAS process. ([#1720](https://github.com/matrix-org/matrix-spec/issues/1720))
+- Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077). ([#1732](https://github.com/matrix-org/matrix-spec/issues/1732))
+- The [font](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font) element is deprecated in the HTML spec. Clients should prefer [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) with the `data-mx-bg-color` and `data-mx-color` attributes instead. ([#1739](https://github.com/matrix-org/matrix-spec/issues/1739))
+- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
+- Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`. ([#1742](https://github.com/matrix-org/matrix-spec/issues/1742))
+- Fix various typos throughout the specification. ([#1748](https://github.com/matrix-org/matrix-spec/issues/1748))
+- Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses. ([#1756](https://github.com/matrix-org/matrix-spec/issues/1756))
+- Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763))
+
+
+## Server-Server API
+
+**Spec Clarifications**
+
+- Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies. ([#1721](https://github.com/matrix-org/matrix-spec/issues/1721))
+- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
+- Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744))
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717))
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Update the spec release process. ([#1680](https://github.com/matrix-org/matrix-spec/issues/1680))
+- Minor clarifications to the contributing guide. ([#1697](https://github.com/matrix-org/matrix-spec/issues/1697))
+- Update Docsy to v0.8.0. ([#1699](https://github.com/matrix-org/matrix-spec/issues/1699), [#1762](https://github.com/matrix-org/matrix-spec/issues/1762))
+- Fix npm release script for `@matrix-org/spec`. ([#1713](https://github.com/matrix-org/matrix-spec/issues/1713))
+- Add some clarifications around implementation requirements for MSCs. ([#1718](https://github.com/matrix-org/matrix-spec/issues/1718))
+- Update HTML templates to include links to object schema definitions. ([#1724](https://github.com/matrix-org/matrix-spec/issues/1724))
+- Factor out all the common parameters of the various `/relations` apis. ([#1745](https://github.com/matrix-org/matrix-spec/issues/1745))
+- Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas. ([#1751](https://github.com/matrix-org/matrix-spec/issues/1751), [#1754](https://github.com/matrix-org/matrix-spec/issues/1754))

content/changelog/v1.11.md

@@ -0,0 +1,161 @@
+---
+title: v1.11 Changelog
+linkTitle: v1.11
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-06-20
+---
+
+## 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/changelog/v1.12.md

@@ -0,0 +1,113 @@
+---
+title: v1.12 Changelog
+linkTitle: v1.12
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-10-07
+---
+
+## Client-Server API
+
+**Deprecations**
+
+- Deprecate the `server_name` query parameter on `POST /_matrix/client/v3/join/{roomIdOrAlias}` and `POST /_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). ([#1933](https://github.com/matrix-org/matrix-spec/issues/1933))
+
+**Removed Endpoints**
+
+- Remove references to device-specific push rules. ([#1842](https://github.com/matrix-org/matrix-spec/issues/1842))
+- Remove the deprecated name attribute on HTML anchor elements, as per [MSC4159](https://github.com/matrix-org/matrix-spec-proposals/pull/4159). ([#1870](https://github.com/matrix-org/matrix-spec/issues/1870))
+
+**Backwards Compatible Changes**
+
+- Add 403 responses on `GET /_matrix/client/v3/profile/{userId}/avatar_url` and `GET /_matrix/client/v3/profile/{userId}/displayname`, as per [MSC4170](https://github.com/matrix-org/matrix-spec-proposals/pull/4170). ([#1867](https://github.com/matrix-org/matrix-spec/issues/1867))
+- Add support for marking rooms as unread, as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867). ([#1895](https://github.com/matrix-org/matrix-spec/issues/1895), [#1941](https://github.com/matrix-org/matrix-spec/issues/1941))
+- Add `via` query parameter on `POST /_matrix/client/v3/join/{roomIdOrAlias}` and `POST /_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). ([#1933](https://github.com/matrix-org/matrix-spec/issues/1933))
+- Add account locking, as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/3939). ([#1934](https://github.com/matrix-org/matrix-spec/issues/1934))
+- Guest accounts can now download/thumbnail media from the new authenticated endpoints, as per [MSC4189](https://github.com/matrix-org/matrix-spec-proposals/pull/4189). ([#1959](https://github.com/matrix-org/matrix-spec/issues/1959))
+
+**Spec Clarifications**
+
+- Rename and sort the modules in the feature profiles table for easier skimming. ([#1855](https://github.com/matrix-org/matrix-spec/issues/1855))
+- Clarify that room avatars cannot be encrypted. ([#1871](https://github.com/matrix-org/matrix-spec/issues/1871))
+- Document the acronyms and alternate names for the "Secrets" section. ([#1875](https://github.com/matrix-org/matrix-spec/issues/1875))
+- Improve recommendation for how to form transaction IDs. ([#1888](https://github.com/matrix-org/matrix-spec/issues/1888))
+- Clarify that the deprecated `dont_notify` and `coalesce` push rule actions MUST be ignored, not rejected. ([#1890](https://github.com/matrix-org/matrix-spec/issues/1890))
+- Fix various typos throughout the specification. ([#1892](https://github.com/matrix-org/matrix-spec/issues/1892))
+- Add missing references to `m.set_displayname`, `m.set_avatar_url`, and `m.3pid_changes` in capabilities table. ([#1897](https://github.com/matrix-org/matrix-spec/issues/1897))
+- Clarify that the fallback login page calls `window.matrixLogin.onLogin` instead of `window.onLogin`. ([#1899](https://github.com/matrix-org/matrix-spec/issues/1899))
+- Remove confusing description of restricted rooms with no valid conditions. ([#1903](https://github.com/matrix-org/matrix-spec/issues/1903))
+- Clarify that `window.matrixLogin.onLogin` is called with the response body of `POST /_matrix/client/v3/login`. ([#1905](https://github.com/matrix-org/matrix-spec/issues/1905))
+- Document the `m.get_login_token` capability, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). ([#1908](https://github.com/matrix-org/matrix-spec/issues/1908))
+- Clarify that the `User identifier` object in `POST /_matrix/client/v3/login` contains additional properties that depend on the identification type. ([#1909](https://github.com/matrix-org/matrix-spec/issues/1909))
+- Don't mention that `GET /_matrix/client/v3/profile/{userId}` can return additional properties because this is true for almost every endpoint. ([#1910](https://github.com/matrix-org/matrix-spec/issues/1910))
+- Improve wording of the unauthenticated media deprecation box. Contributed by @HarHarLinks. ([#1916](https://github.com/matrix-org/matrix-spec/issues/1916))
+- Additional properties in `GET /.well-known/matrix/client` don't have to be objects. ([#1920](https://github.com/matrix-org/matrix-spec/issues/1920))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+- Specify `Content-Type` and `Content-Disposition` usage in the media repo, as per [MSC2701](https://github.com/matrix-org/matrix-spec-proposals/pull/2701) and [MSC2702](https://github.com/matrix-org/matrix-spec-proposals/pull/2702). ([#1935](https://github.com/matrix-org/matrix-spec/issues/1935))
+- Additional keys in `GET /_matrix/client/v3/capabilities` don't have to be objects. ([#1945](https://github.com/matrix-org/matrix-spec/issues/1945))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Add 403 response on `GET /_matrix/federation/v1/query/profile`, as per [MSC4170](https://github.com/matrix-org/matrix-spec-proposals/pull/4170). ([#1867](https://github.com/matrix-org/matrix-spec/issues/1867))
+
+**Spec Clarifications**
+
+- Remove `origin` field from PDU example because it doesn't exist in the schema anymore. ([#1918](https://github.com/matrix-org/matrix-spec/issues/1918))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+- Fix required fields in `GET /_matrix/key/v2/server` response schema. ([#1930](https://github.com/matrix-org/matrix-spec/issues/1930))
+- Use "server name" instead of "DNS name" to avoid confusion with the "DNS name" component of "server names" as defined in the appendices. ([#1946](https://github.com/matrix-org/matrix-spec/issues/1946))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Push Gateway API
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- Fix a formatting issue in state resolution v2. ([#1896](https://github.com/matrix-org/matrix-spec/issues/1896))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- The Matrix.org Foundation no longer requires "real" or "legally identifiable" names in order to contribute to projects. ([#1886](https://github.com/matrix-org/matrix-spec/issues/1886), [#1914](https://github.com/matrix-org/matrix-spec/issues/1914))
+- Document the `removal` changelog category. ([#1907](https://github.com/matrix-org/matrix-spec/issues/1907))
+- Use dedicated fonts for better support of mathematical symbols. ([#1919](https://github.com/matrix-org/matrix-spec/issues/1919))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+- Provide markdown checklists for changelogs under `/changelog/$VERSION/checklist.md`. ([#1937](https://github.com/matrix-org/matrix-spec/issues/1937), [#1954](https://github.com/matrix-org/matrix-spec/issues/1954))
+- Add the `deprecated` field to properties of OpenAPI definitions and JSON Schemas. ([#1940](https://github.com/matrix-org/matrix-spec/issues/1940))
+- Use relative permalink to redirect to latest changelog. ([#1956](https://github.com/matrix-org/matrix-spec/issues/1956))

content/changelog/v1.13.md

@@ -0,0 +1,108 @@
+---
+title: v1.13 Changelog
+linkTitle: v1.13
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-12-19
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `POST /_matrix/client/v3/rooms/{roomId}/report`, as per [MSC4151](https://github.com/matrix-org/matrix-spec-proposals/pull/4151). ([#1938](https://github.com/matrix-org/matrix-spec/issues/1938), [#2028](https://github.com/matrix-org/matrix-spec/issues/2028))
+
+**Backwards Compatible Changes**
+
+- Add error codes to requestToken endpoints, as per [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178). ([#1944](https://github.com/matrix-org/matrix-spec/issues/1944))
+- Remove reply fallbacks, as per [MSC2781](https://github.com/matrix-org/matrix-spec-proposals/issues/2781). ([#1994](https://github.com/matrix-org/matrix-spec/issues/1994))
+- Clarify the allowed HTTP methods in CORS responses, as per [MSC4138](https://github.com/matrix-org/matrix-spec-proposals/pull/4138). ([#1995](https://github.com/matrix-org/matrix-spec/issues/1995), [#2011](https://github.com/matrix-org/matrix-spec/issues/2011))
+- Add new `M_USER_SUSPENDED` error code behaviour, as per [MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823). ([#2014](https://github.com/matrix-org/matrix-spec/issues/2014))
+
+**Spec Clarifications**
+
+- The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank, as per [MSC2414](https://github.com/matrix-org/matrix-spec-proposals/pull/2414). ([#1938](https://github.com/matrix-org/matrix-spec/issues/1938))
+- Correct OpenAPI specification for query parameters to `GET /_matrix/client/v3/thirdparty/location/{protocol}` endpoint. ([#1947](https://github.com/matrix-org/matrix-spec/issues/1947))
+- Sort VoIP events semantically. ([#1967](https://github.com/matrix-org/matrix-spec/issues/1967))
+- Clarify that servers must forward custom keys in `PusherData` when sending notifications to the push gateway. ([#1973](https://github.com/matrix-org/matrix-spec/issues/1973))
+- Clarify formats of string types. ([#1978](https://github.com/matrix-org/matrix-spec/issues/1978), [#1979](https://github.com/matrix-org/matrix-spec/issues/1979), [#1980](https://github.com/matrix-org/matrix-spec/issues/1980))
+- Clarify that the async upload endpoint will return 404 in some cases. ([#1983](https://github.com/matrix-org/matrix-spec/issues/1983))
+- Remove distinction between `StateFilter` and `RoomEventFilter`. ([#2015](https://github.com/matrix-org/matrix-spec/issues/2015))
+- Add hyperlinks throughout the specification. ([#2016](https://github.com/matrix-org/matrix-spec/issues/2016))
+- Use `json` instead of `json5` for syntax highlighting. ([#2017](https://github.com/matrix-org/matrix-spec/issues/2017))
+- Specify order that one-time keys are issued by `/keys/claim`, as per [MSC4225](https://github.com/matrix-org/matrix-spec-proposals/pull/4225). ([#2029](https://github.com/matrix-org/matrix-spec/issues/2029))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Make ACLs apply to EDUs, as per [MSC4163](https://github.com/matrix-org/matrix-spec-proposals/pull/4163). ([#2004](https://github.com/matrix-org/matrix-spec/issues/2004))
+
+**Spec Clarifications**
+
+- Add 403 error response to `/_matrix/federation/v1/state_ids/{roomId}`. ([#1926](https://github.com/matrix-org/matrix-spec/issues/1926))
+
+
+## Application Service API
+
+**Backwards Compatible Changes**
+
+- Allow sending ephemeral data to application services, as per [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409). ([#2018](https://github.com/matrix-org/matrix-spec/issues/2018))
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+**Spec Clarifications**
+
+- Document the schema of `PusherData`. ([#1968](https://github.com/matrix-org/matrix-spec/issues/1968))
+- The path of HTTP pusher URLs is fixed to `/_matrix/push/v1/notify`. ([#1974](https://github.com/matrix-org/matrix-spec/issues/1974))
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- Clarify rule 4.3.1 of the auth rules in room version 11 to state which event's `sender` the `state_key` needs to match. ([#2024](https://github.com/matrix-org/matrix-spec/issues/2024))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Remove note about reference implementations. ([#1966](https://github.com/matrix-org/matrix-spec/issues/1966))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Add `x-weight` property for sorting events rendered with the `event-group` shortcode. ([#1967](https://github.com/matrix-org/matrix-spec/issues/1967))
+- Enforce consistent vertical spacing between paragraphs in endpoint definitions. ([#1969](https://github.com/matrix-org/matrix-spec/issues/1969), [#2005](https://github.com/matrix-org/matrix-spec/issues/2005))
+- Remove `boxes/added-in-paragraph` shortcode. ([#1970](https://github.com/matrix-org/matrix-spec/issues/1970))
+- Remove `withVersioning` parameter of `rver-fragment` shortcode. ([#1971](https://github.com/matrix-org/matrix-spec/issues/1971))
+- Remove `span` element from `added-in` and `changed-in` shortcodes. ([#1972](https://github.com/matrix-org/matrix-spec/issues/1972))
+- Fix formatting of `added-in` and `changed-in` shortcodes by using `%` delimiter. ([#1975](https://github.com/matrix-org/matrix-spec/issues/1975))
+- Remove CSS workaround for scroll-anchoring. ([#1976](https://github.com/matrix-org/matrix-spec/issues/1976))
+- Rename `custom-formats.yaml` to `string-formats.yaml` and update its docs. ([#1977](https://github.com/matrix-org/matrix-spec/issues/1977))
+- Fix relative URLs when serving the specification with a custom `baseURL`. ([#1984](https://github.com/matrix-org/matrix-spec/issues/1984), [#1997](https://github.com/matrix-org/matrix-spec/issues/1997))
+- Rename `.htmltest.yaml` to `.htmltest.yml`. ([#1985](https://github.com/matrix-org/matrix-spec/issues/1985))
+- Improve the JS script to highlight the current ToC entry. ([#1991](https://github.com/matrix-org/matrix-spec/issues/1991), [#2002](https://github.com/matrix-org/matrix-spec/issues/2002))
+- Upgrade docsy to 0.11.0 and hugo to 0.139.0. ([#1996](https://github.com/matrix-org/matrix-spec/issues/1996), [#2007](https://github.com/matrix-org/matrix-spec/issues/2007))
+- Improve the quality of the rendered diagrams ([#1999](https://github.com/matrix-org/matrix-spec/issues/1999))
+- Update the Inter font and allow the browser to render the page before it is loaded ([#2000](https://github.com/matrix-org/matrix-spec/issues/2000))
+- Use a proper Matrix favicon ([#2001](https://github.com/matrix-org/matrix-spec/issues/2001))
+- Clean up unused CSS classes in `openapi/render-operation` partial. ([#2003](https://github.com/matrix-org/matrix-spec/issues/2003))
+- Fix `changed-in` partial when used with multiple paragraphs. ([#2006](https://github.com/matrix-org/matrix-spec/issues/2006))
+- Optimize generated CSS by removing unused selectors. ([#2008](https://github.com/matrix-org/matrix-spec/issues/2008))
+- Remove trailing slash on void HTML elements. ([#2009](https://github.com/matrix-org/matrix-spec/issues/2009))
+- Remove `type` and `language` attributes of `script` element. ([#2021](https://github.com/matrix-org/matrix-spec/issues/2021))
+- Change the accessible role of info boxes to `note`. ([#2022](https://github.com/matrix-org/matrix-spec/issues/2022))

content/changelog/v1.2.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-02-02T00:00:00+0000
+title: v1.2 Changelog
+linkTitle: v1.2
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-02-02
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
+## Client-Server API
-    v1.2  = Replaced by the version number (eg: v1.2)
-    February 02, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.2
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.2">https://github.com/matrix-org/matrix-doc/tree/v1.2</a></td>
-<tr><th>Release date</th><td>February 02, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
 
 
 <strong>Breaking Changes</strong>
@@ -65,7 +57,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>New Endpoints</strong>
@@ -88,7 +80,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -99,7 +91,7 @@ Variables:
 - Correct the documentation for the response value for `GET /_matrix/app/v1/thirdparty/protocol/{protocol}`. ([#3675](https://github.com/matrix-org/matrix-doc/issues/3675))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -114,7 +106,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Spec Clarifications</strong>
@@ -123,7 +115,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -144,7 +136,7 @@ Variables:
 - Fix auth rules to allow membership of `knock` -> `leave` in v7, v8, and v9. ([#3694](https://github.com/matrix-org/matrix-doc/issues/3694))
 
 
-### Appendices
+## Appendices
 
 
 <strong>Backwards Compatible Changes</strong>

content/changelog/v1.3.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-06-15T00:00:00+0100
+title: v1.3 Changelog
+linkTitle: v1.3
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-06-15
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
+## Client-Server API
-    v1.3  = Replaced by the version number (eg: v1.2)
-    June 15, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.3
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.3">https://github.com/matrix-org/matrix-spec/tree/v1.3</a></td>
-<tr><th>Release date</th><td>June 15, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
 
 
 <strong>Deprecations</strong>
@@ -55,7 +47,7 @@ Variables:
 - Fix membership state transitions to denote that `invite->knock` and `external->leave` are valid transitions. ([#3730](https://github.com/matrix-org/matrix-spec-proposals/issues/3730))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -79,7 +71,7 @@ Variables:
 - Clarify that the `content` for `X-Matrix` signature validation is the parsed JSON body. ([#3727](https://github.com/matrix-org/matrix-spec-proposals/issues/3727))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -88,19 +80,19 @@ Variables:
 - Add timestamp massaging as per [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316). ([#1094](https://github.com/matrix-org/matrix-spec/issues/1094))
 
 
-### Identity Service API
+## Identity Service API
 
 
 No significant changes.
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -124,7 +116,7 @@ No significant changes.
 - For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.

content/changelog/v1.4.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-09-29T00:00:00+0100
+title: v1.4 Changelog
+linkTitle: v1.4
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-09-29
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
+## Client-Server API
-    v1.4  = Replaced by the version number (eg: v1.2)
-    September 29, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.4
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.4">https://github.com/matrix-org/matrix-spec/tree/v1.4</a></td>
-<tr><th>Release date</th><td>September 29, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
 
 
 <strong>Removed Endpoints</strong>
@@ -58,7 +50,7 @@ Variables:
 - Clarify enum values by separating possible values with commas. ([#1240](https://github.com/matrix-org/matrix-spec/issues/1240))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -75,7 +67,7 @@ Variables:
 - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Breaking Changes</strong>
@@ -90,7 +82,7 @@ Variables:
 - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -100,7 +92,7 @@ Variables:
 - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Spec Clarifications</strong>
@@ -109,7 +101,7 @@ Variables:
 - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174))
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Spec Clarifications</strong>
@@ -120,13 +112,13 @@ Variables:
 - For room versions 7 through 10: Clarify that `invite->knock` is actually a legal transition. ([#1175](https://github.com/matrix-org/matrix-spec/issues/1175))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Backwards Compatible Changes</strong>

content/changelog/v1.5.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-11-17T08:22:11-07:00
+title: v1.5 Changelog
+linkTitle: v1.5
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-11-17
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
+## Client-Server API
-    v1.5  = Replaced by the version number (eg: v1.2)
-    November 17, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.5
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.5">https://github.com/matrix-org/matrix-spec/tree/v1.5</a></td>
-<tr><th>Release date</th><td>November 17, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -45,7 +37,7 @@ Variables:
 - Add example read receipt to `GET /_matrix/client/v3/sync` response example. ([#1341](https://github.com/matrix-org/matrix-spec/issues/1341))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Spec Clarifications</strong>
@@ -54,7 +46,7 @@ Variables:
 - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -63,7 +55,7 @@ Variables:
 - Clarify that application services can only register an interest in local users, as per [MSC3905](https://github.com/matrix-org/matrix-spec-proposals/issues/3905). ([#1305](https://github.com/matrix-org/matrix-spec/issues/1305))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -72,13 +64,13 @@ Variables:
 - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Spec Clarifications</strong>
@@ -89,13 +81,13 @@ No significant changes.
 - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Backwards Compatible Changes</strong>

content/changelog/v1.6.md

@@ -1,23 +1,15 @@
 ---
-date: 2023-02-14T08:25:40-07:00
+title: v1.6 Changelog
+linkTitle: v1.6
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-02-14
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
+## Client-Server API
-    v1.6  = Replaced by the version number (eg: v1.2)
-    February 14, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.6
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.6">https://github.com/matrix-org/matrix-spec/tree/v1.6</a></td>
-<tr><th>Release date</th><td>February 14, 2023</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -45,7 +37,7 @@ Variables:
 - Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. ([#1433](https://github.com/matrix-org/matrix-spec/issues/1433))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Breaking Changes</strong>
@@ -73,7 +65,7 @@ Variables:
 - Fix `edu_type` in EDU examples. ([#1383](https://github.com/matrix-org/matrix-spec/issues/1383))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -82,7 +74,7 @@ Variables:
 - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -91,7 +83,7 @@ Variables:
 - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -100,7 +92,7 @@ Variables:
 - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -116,13 +108,13 @@ Variables:
 - Fix various typos throughout the specification. ([#1423](https://github.com/matrix-org/matrix-spec/issues/1423))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Spec Clarifications</strong>

content/changelog/v1.7.md

@@ -1,23 +1,15 @@
 ---
-date: 2023-05-25T09:47:21-06:00
+title: v1.7 Changelog
+linkTitle: v1.7
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-05-25
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
+## Client-Server API
-    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>
@@ -63,7 +55,7 @@ Variables:
 - 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
+## Server-Server API
 
 
 <strong>Spec Clarifications</strong>
@@ -75,7 +67,7 @@ Variables:
 - Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>New Endpoints</strong>
@@ -97,7 +89,7 @@ Variables:
 - Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -106,13 +98,13 @@ Variables:
 - Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Spec Clarifications</strong>
@@ -121,7 +113,7 @@ No significant changes.
 - Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
 
 
-### Appendices
+## Appendices
 
 
 <strong>Spec Clarifications</strong>
@@ -132,7 +124,7 @@ No significant changes.
 - Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Spec Clarifications</strong>

content/changelog/v1.8.md

@@ -0,0 +1,113 @@
+---
+title: v1.8 Changelog
+linkTitle: v1.8
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-08-23
+---
+
+## Client-Server API
+
+**Backwards Compatible Changes**
+
+- Require callers to be joined to the room to report its events, as per [MSC2249](https://github.com/matrix-org/matrix-spec-proposals/pull/2249). ([#1517](https://github.com/matrix-org/matrix-spec/issues/1517))
+
+**Spec Clarifications**
+
+- Fix missing `type` property in the JSON schema definition of the `m.reaction` event.  Contributed by @chebureki. ([#1552](https://github.com/matrix-org/matrix-spec/issues/1552))
+- Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563))
+- Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas. ([#1564](https://github.com/matrix-org/matrix-spec/issues/1564))
+- Fix broken header formatting. Contributed by @midnightveil. ([#1578](https://github.com/matrix-org/matrix-spec/issues/1578))
+- Render binary request and response bodies. ([#1579](https://github.com/matrix-org/matrix-spec/issues/1579))
+- Fix description of MAC calculation in SAS verification. ([#1590](https://github.com/matrix-org/matrix-spec/issues/1590))
+- Update link to SAS emoji definition data. ([#1593](https://github.com/matrix-org/matrix-spec/issues/1593))
+- Fix various typos throughout the specification. ([#1597](https://github.com/matrix-org/matrix-spec/issues/1597))
+
+
+## Server-Server API
+
+**Deprecations**
+
+- Deprecate `matrix` SRV lookup steps during server discovery, as per [MSC4040](https://github.com/matrix-org/matrix-spec-proposals/pull/4040). ([#1624](https://github.com/matrix-org/matrix-spec/issues/1624))
+
+**Backwards Compatible Changes**
+
+- Add `matrix-fed` SRV lookup steps to server discovery, as per [MSC4040](https://github.com/matrix-org/matrix-spec-proposals/pull/4040). ([#1624](https://github.com/matrix-org/matrix-spec/issues/1624))
+
+**Spec Clarifications**
+
+- Document why `/state_ids` can respond with a 404. ([#1521](https://github.com/matrix-org/matrix-spec/issues/1521))
+- Fix response definition for `POST /_matrix/federation/v1/user/keys/claim`. ([#1559](https://github.com/matrix-org/matrix-spec/issues/1559))
+- Fix examples in server keys definition. ([#1560](https://github.com/matrix-org/matrix-spec/issues/1560))
+- Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563))
+- Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas. ([#1564](https://github.com/matrix-org/matrix-spec/issues/1564))
+- Fix broken header formatting. Contributed by @midnightveil. ([#1578](https://github.com/matrix-org/matrix-spec/issues/1578))
+- Remove spurious mention of a "default port" with respect to SRV record lookup. ([#1615](https://github.com/matrix-org/matrix-spec/issues/1615))
+- Switch to ordered list for server name resolution steps. ([#1623](https://github.com/matrix-org/matrix-spec/issues/1623))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Fix type of custom `fields` in thirdparty lookup queries. ([#1584](https://github.com/matrix-org/matrix-spec/issues/1584))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Backwards Compatible Changes**
+
+- Add room version 11 as per [MSC3820](https://github.com/matrix-org/matrix-spec-proposals/pull/3820). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Move `redacts` from top level to `content` on `m.room.redaction` events in room version 11, as per [MSC2174](https://github.com/matrix-org/matrix-spec-proposals/pull/2174). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Remove `creator` from `m.room.creator` events in room version 11, as per [MSC2175](https://github.com/matrix-org/matrix-spec-proposals/pull/2175). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Remove remaining usage of `origin` from events in room version 11, as per [MSC3989](https://github.com/matrix-org/matrix-spec-proposals/pull/3989). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Update the redaction rules in room version 11, as per [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) and [MSC3821](https://github.com/matrix-org/matrix-spec-proposals/pull/3821). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+
+
+## Appendices
+
+**Backwards Compatible Changes**
+
+- Allow `+` in Matrix IDs, as per [MSC4009](https://github.com/matrix-org/matrix-spec-proposals/pull/4009). ([#1583](https://github.com/matrix-org/matrix-spec/issues/1583))
+
+**Spec Clarifications**
+
+- Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten. ([#1573](https://github.com/matrix-org/matrix-spec/issues/1573))
+
+
+## Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Upgrade Swagger data to OpenAPI 3.1. ([#1310](https://github.com/matrix-org/matrix-spec/issues/1310))
+- Create `@matrix-org/spec` npm package to ship the SAS Emoji data definitions & translations. ([#1620](https://github.com/matrix-org/matrix-spec/issues/1620))
+
+**Spec Clarifications**
+
+- Update the CI to validate the file extension of changelog entries. ([#1542](https://github.com/matrix-org/matrix-spec/issues/1542))
+- Disclosure sections now only display their title when collapsed. ([#1549](https://github.com/matrix-org/matrix-spec/issues/1549))
+- Fix the sidebar in recent versions of Hugo. ([#1551](https://github.com/matrix-org/matrix-spec/issues/1551))
+- Bump jsonschema to validate JSON Schemas against Draft 2020-12. ([#1556](https://github.com/matrix-org/matrix-spec/issues/1556))
+- Use Redocly CLI to validate OpenAPI definitions. ([#1558](https://github.com/matrix-org/matrix-spec/issues/1558))
+- Use tag name as the OpenAPI definition version. ([#1561](https://github.com/matrix-org/matrix-spec/issues/1561))
+- Make sure version in `x-changedInMatrixVersion` is a string. ([#1562](https://github.com/matrix-org/matrix-spec/issues/1562))
+- Clarify usage of ABNF for grammar in the documentation style guide. ([#1582](https://github.com/matrix-org/matrix-spec/issues/1582))
+- Remove unnecessary `oneOf`s in JSON schemas. ([#1585](https://github.com/matrix-org/matrix-spec/issues/1585))
+- Update the version of Hugo used to render the spec to v0.113.0. ([#1591](https://github.com/matrix-org/matrix-spec/issues/1591))
+- Fix rendered changelog with new version of towncrier. ([#1598](https://github.com/matrix-org/matrix-spec/issues/1598))
+- Improve the layout of tables on desktop displays. Contributed by Martin Fischer. ([#1601](https://github.com/matrix-org/matrix-spec/issues/1601))

content/changelog/v1.9.md

@@ -0,0 +1,84 @@
+---
+title: v1.9 Changelog
+linkTitle: v1.9
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-11-29
+---
+
+## Client-Server API
+
+**Backwards Compatible Changes**
+
+- Add the `m.rule.suppress_edits` default push rule, as per [MSC3958](https://github.com/matrix-org/matrix-spec-proposals/pull/3958). ([#1617](https://github.com/matrix-org/matrix-spec/issues/1617))
+
+**Spec Clarifications**
+
+- Fix `m.call.negotiate` schema and example. ([#1546](https://github.com/matrix-org/matrix-spec/issues/1546))
+- Clarify that the `via` property is required for `m.space.parent` and `m.space.child` as per [MSC1772](https://github.com/matrix-org/matrix-spec-proposals/pull/1772). Contributed by @PaarthShah. ([#1618](https://github.com/matrix-org/matrix-spec/issues/1618))
+- Add a note to the `/publicRooms` API that the server name is case sensitive. ([#1638](https://github.com/matrix-org/matrix-spec/issues/1638))
+- Clarify that an `m.room.name` event with an absent `name` field is not expected behavior. ([#1639](https://github.com/matrix-org/matrix-spec/issues/1639))
+- Fix schemas used for account data and presence events in `GET /initialSync`. ([#1647](https://github.com/matrix-org/matrix-spec/issues/1647))
+- Fix various typos throughout the specification. ([#1658](https://github.com/matrix-org/matrix-spec/issues/1658), [#1661](https://github.com/matrix-org/matrix-spec/issues/1661), [#1665](https://github.com/matrix-org/matrix-spec/issues/1665))
+- Fix `.m.rule.suppress_notices` push rule not being valid JSON. ([#1671](https://github.com/matrix-org/matrix-spec/issues/1671))
+- Add missing properties for `event_property_is` and `event_property_contains` push conditions to `PushConditions` object. ([#1673](https://github.com/matrix-org/matrix-spec/issues/1673))
+- Indicate that fallback keys should have a `fallback` property set to `true`. ([#1676](https://github.com/matrix-org/matrix-spec/issues/1676))
+- Clarify that thread roots are not considered within the thread. ([#1677](https://github.com/matrix-org/matrix-spec/issues/1677))
+
+
+## Server-Server API
+
+**Spec Clarifications**
+
+- Fix schema of `m.receipt` EDU. ([#1636](https://github.com/matrix-org/matrix-spec/issues/1636))
+- Fix various typos throughout the specification. ([#1661](https://github.com/matrix-org/matrix-spec/issues/1661))
+- Clarify that federation requests for non-local users are invalid. ([#1672](https://github.com/matrix-org/matrix-spec/issues/1672))
+
+
+## Application Service API
+
+No significant changes.
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+No significant changes.
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Clarify timestamp specification with respect to leap seconds. ([#1627](https://github.com/matrix-org/matrix-spec/issues/1627))
+- Fix various typos throughout the specification. ([#1652](https://github.com/matrix-org/matrix-spec/issues/1652))
+
+
+## Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Add more CI checks for OpenAPI definitions and JSON Schemas. ([#1656](https://github.com/matrix-org/matrix-spec/issues/1656))
+- Generate server-server OpenAPI definition. ([#1657](https://github.com/matrix-org/matrix-spec/issues/1657))
+
+**Spec Clarifications**
+
+- Replace all mentions of Swagger by OpenAPI. ([#1633](https://github.com/matrix-org/matrix-spec/issues/1633))
+- Fix enum types in JSON schemas. ([#1634](https://github.com/matrix-org/matrix-spec/issues/1634))
+- Fix schema of `m.mentions` object. ([#1635](https://github.com/matrix-org/matrix-spec/issues/1635))
+- Fix rendering of `m.receipt` event in Client-Server API. ([#1637](https://github.com/matrix-org/matrix-spec/issues/1637))
+- Remove required `fieldname` in appservice Protocol definition. ([#1646](https://github.com/matrix-org/matrix-spec/issues/1646))
+- Fix github action workflow responsible for releasing of @matrix-org/spec package. ([#1648](https://github.com/matrix-org/matrix-spec/issues/1648))
+- Upgrade GitHub actions. ([#1660](https://github.com/matrix-org/matrix-spec/issues/1660))

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.
@@ -94,6 +100,13 @@ section](#soft-logout) for more information.
 `M_MISSING_TOKEN`
 No access token was specified for the request.
 
+`M_USER_LOCKED`
+The account has been [locked](#account-locking) and cannot be used at this time.
+
+`M_USER_SUSPENDED`
+The account has been [suspended](#account-suspension) and can only be used for
+limited actions at this time.
+
 `M_BAD_JSON`
 Request contained valid JSON, but it was malformed in some way, e.g.
 missing required keys, invalid values for keys.
@@ -106,7 +119,7 @@ No resource was found for this request.
 
 `M_LIMIT_EXCEEDED`
 Too many requests have been sent in a short period of time. Wait a while
-then try again.
+then try again. See [Rate limiting](#rate-limiting).
 
 `M_UNRECOGNIZED`
 The server did not understand the request. This is expected to be returned with
@@ -127,7 +140,7 @@ The request was not correctly authorized. Usually due to login failures.
 
 `M_USER_DEACTIVATED`
 The user ID associated with the request has been deactivated. Typically
-for endpoints that prove authentication, such as `/login`.
+for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
 
 `M_USER_IN_USE`
 Encountered when trying to register a user ID which has been taken.
@@ -206,12 +219,43 @@ much memory or disk space. The error MUST have an `admin_contact` field
 to provide the user receiving the error a place to reach out to.
 Typically, this error will appear on routes which attempt to modify
 state (e.g.: sending messages, account data, etc) and not routes which
-only read state (e.g.: `/sync`, get account data, etc).
+only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
+[`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
 
 `M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
 The user is unable to reject an invite to join the server notices room.
 See the [Server Notices](#server-notices) module for more information.
 
+`M_THREEPID_MEDIUM_NOT_SUPPORTED`
+The homeserver does not support adding a third party identifier of the given medium.
+
+`M_THREEPID_IN_USE`
+The third party identifier specified by the client is not acceptable because it is
+already in use in some way.
+
+#### Rate limiting
+
+Homeservers SHOULD implement rate limiting to reduce the risk of being
+overloaded. If a request is refused due to rate limiting, it should
+return a standard error response of the form:
+
+```json
+{
+  "errcode": "M_LIMIT_EXCEEDED",
+  "error": "string",
+  "retry_after_ms": integer (optional, deprecated)
+}
+```
+
+Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after)
+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
+deprecated, in favour of the `Retry-After` header.
+
+{{% changed-in v="1.10" %}}: `retry_after_ms` property deprecated in favour of `Retry-After` header.
+
 ### Transaction identifiers
 
 The client-server API typically uses `HTTP PUT` to submit requests with
@@ -223,9 +267,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
@@ -233,7 +278,7 @@ HTTP request is the same.
 
 Where a retransmission has been identified, the homeserver should return
 the same HTTP response code and content as the original request.
-For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`
+For example, [`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
 would return a `200 OK` with the `event_id` of the original request in
 the response body.
 
@@ -284,6 +329,15 @@ headers to be returned by servers on all requests are:
     Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
     Access-Control-Allow-Headers: X-Requested-With, Content-Type, Authorization
 
+{{% boxes/note %}}
+{{% added-in v="1.13" %}} The recommended value of the `Access-Control-Allow-Methods`
+header only covers the existing endpoints in the specification. Servers which
+support additional endpoints or methods should add those methods as well.
+
+This section will be updated whenever a new method is supported by an endpoint.
+Examples of possible future-use methods include `PATCH` and `HEAD`.
+{{% /boxes/note %}}
+
 ## Server Discovery
 
 In order to allow users to connect to a Matrix server without needing to
@@ -327,9 +381,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
@@ -363,11 +417,12 @@ specify parameter values. The flow for this method is as follows:
 
 {{% http-api spec="client-server" api="versions" %}}
 
+{{% http-api spec="client-server" api="support" %}}
+
 ## Client Authentication
 
 Most API endpoints require the user to identify themselves by presenting
-previously obtained credentials in the form of an `access_token` query
+previously obtained credentials in the form of an access token.
-parameter or through an Authorization Header of `Bearer $access_token`.
 An access token is typically obtained via the [Login](#login) or
 [Registration](#account-registration-and-management) processes. Access tokens
 can expire; a new access token can be generated by using a refresh token.
@@ -381,16 +436,19 @@ investigate [macaroons](http://research.google.com/pubs/pub41892.html).
 
 ### Using access tokens
 
-Access tokens may be provided in two ways, both of which the homeserver
+Access tokens may be provided via a request header, using the Authentication
-MUST support:
+Bearer scheme: `Authorization: Bearer TheTokenHere`.
 
-1.  Via a query string parameter, `access_token=TheTokenHere`.
+Clients may alternatively provide the access token via a query string parameter:
-2.  Via a request header, `Authorization: Bearer TheTokenHere`.
+`access_token=TheTokenHere`. This method is deprecated to prevent the access
+token being leaked in access/HTTP logs and SHOULD NOT be used by clients.
 
-Clients are encouraged to use the `Authorization` header where possible
+Homeservers MUST support both methods.
-to prevent the access token being leaked in access/HTTP logs. The query
+
-string should only be used in cases where the `Authorization` header is
+{{% boxes/note %}}
-inaccessible for the client.
+{{% changed-in v="1.11" %}}
+Sending the access token as a query string parameter is now deprecated.
+{{% /boxes/note %}}
 
 When credentials are required but missing or invalid, the HTTP call will
 return with a status of 401 and the error code, `M_MISSING_TOKEN` or
@@ -400,7 +458,7 @@ could mean one of four things:
 1. the access token was never valid.
 2. the access token has been logged out.
 3. the access token has been [soft logged out](#soft-logout).
-4. {{< added-in v="1.3" >}} the access token [needs to be refreshed](#refreshing-access-tokens).
+4. {{% added-in v="1.3" %}} the access token [needs to be refreshed](#refreshing-access-tokens).
 
 When a client receives an error code of `M_UNKNOWN_TOKEN`, it should:
 
@@ -483,6 +541,10 @@ token available. If it does not have a refresh token available, or refreshing
 fails with `soft_logout: true`, the client can acquire a new access token by
 specifying the device ID it is already using to the login API.
 
+{{% changed-in v="1.12" %}} A client that receives such a response together
+with an `M_USER_LOCKED` error code, cannot obtain a new access token until
+the account has been [unlocked](#account-locking).
+
 ### User-Interactive Authentication API
 
 #### Overview
@@ -520,8 +582,10 @@ request parameter.
 A client should first make a request with no `auth` parameter.
 The homeserver returns an HTTP 401 response, with a JSON body, as follows:
 
-    HTTP/1.1 401 Unauthorized
+```
-    Content-Type: application/json
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -564,8 +628,10 @@ given. It also contains other keys dependent on the auth type being
 attempted. For example, if the client is attempting to complete auth
 type `example.type.foo`, it might submit something like this:
 
-    POST /_matrix/client/v3/endpoint HTTP/1.1
+```
-    Content-Type: application/json
+POST /_matrix/client/v3/endpoint HTTP/1.1
+Content-Type: application/json
+```
 
 ```json
 {
@@ -585,8 +651,10 @@ along with the same object as when no authentication was attempted, with
 the addition of the `completed` key which is an array of auth types the
 client has completed successfully:
 
-    HTTP/1.1 401 Unauthorized
+```
-    Content-Type: application/json
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -617,8 +685,10 @@ but the client may make a second attempt, it returns the same HTTP
 status 401 response as above, with the addition of the standard
 `errcode` and `error` fields describing the error. For example:
 
-    HTTP/1.1 401 Unauthorized
+```
-    Content-Type: application/json
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -645,8 +715,10 @@ status 401 response as above, with the addition of the standard
 If the request fails for a reason other than authentication, the server
 returns an error message in the standard format. For example:
 
-    HTTP/1.1 400 Bad request
+```
-    Content-Type: application/json
+HTTP/1.1 400 Bad request
+Content-Type: application/json
+```
 
 ```json
 {
@@ -843,7 +915,7 @@ follows:
 ```
 
 Note that `id_server` (and therefore `id_access_token`) is optional if
-the `/requestToken` request did not include them.
+the [`/requestToken`](#post_matrixclientv3registeremailrequesttoken) request did not include them.
 
 ##### Phone number/MSISDN-based (identity / homeserver)
 
@@ -872,7 +944,7 @@ follows:
 ```
 
 Note that `id_server` (and therefore `id_access_token`) is optional if
-the `/requestToken` request did not include them.
+the [`/requestToken`](#post_matrixclientv3registermsisdnrequesttoken) request did not include them.
 
 ##### Dummy Auth
 
@@ -919,11 +991,12 @@ or completely closed registration (where the homeserver administrators create
 and distribute accounts).
 
 The token required for this authentication type is shared out of band from
-Matrix and is an opaque string with maximum length of 64 characters in the
+Matrix and is an opaque string using the [Opaque Identifier
-range `[A-Za-z0-9._~-]`. The server can keep any number of tokens for any
+Grammar](/appendices#opaque-identifiers), with maximum length of 64
-length of time/validity. Such cases might be a token limited to 100 uses or
+characters. The server can keep any number of tokens for any length of
-for the next 2 hours - after the tokens expire, they can no longer be used
+time/validity. Such cases might be a token limited to 100 uses or for the next
-to create accounts.
+2 hours - after the tokens expire, they can no longer be used to create
+accounts.
 
 To use this authentication type, clients should submit an auth dict with just
 the type, token, and session:
@@ -943,6 +1016,129 @@ in the registration process that their token has expired.
 
 {{% http-api spec="client-server" api="registration_tokens" %}}
 
+##### Terms of service at registration
+
+{{% added-in v="1.11" %}}
+
+| Type                     | Description                                                              |
+|--------------------------|--------------------------------------------------------------------------|
+| `m.login.terms`          | Authentication requires the user to accept a set of policy documents. |
+
+{{% boxes/note %}}
+The `m.login.terms` authentication type is only valid on the
+[`/register`](#post_matrixclientv3register) endpoint.
+{{% /boxes/note %}}
+
+This authentication type is used when the homeserver requires new users to
+accept a given set of policy documents, such as a terms of service and a privacy
+policy. There may be many different types of documents, all of which are
+versioned and presented in (potentially) multiple languages.
+
+When the server requires the user to accept some terms, it does so by returning
+a 401 response to the `/register` request, where the response body includes
+`m.login.terms` in the `flows` list, and the `m.login.terms` property in the
+`params` object has the structure [shown below](#definition-mloginterms-params).
+
+If a client encounters an invalid parameter, registration should stop with an
+error presented to the user.
+
+The client should present the user with a checkbox to accept each policy,
+including a link to the provided URL. Once the user has done so, the client
+submits an `auth` dict with just the `type` and `session`, as follows, to
+indicate that all of the policies have been accepted:
+
+```json
+{
+  "type": "m.login.terms",
+  "session": "<session ID>"
+}
+```
+
+The server is expected to track which document versions it presented to the
+user during registration, if applicable.
+
+
+**Example**
+
+1. A client might submit a registration request as follows:
+
+   ```
+   POST /_matrix/client/v3/register
+   ```
+   ```json
+   {
+     "username": "cheeky_monkey",
+     "password": "ilovebananas"
+   }
+   ```
+
+2. The server requires the user to accept some terms of service before
+   registration, so returns the following response:
+
+   ```
+   HTTP/1.1 401 Unauthorized
+   Content-Type: application/json
+   ```
+   ```json
+   {
+     "flows": [
+       { "stages": [ "m.login.terms" ] }
+     ],
+     "params": {
+       "m.login.terms": {
+         "policies": {
+           "terms_of_service": {
+             "version": "1.2",
+             "en": {
+                 "name": "Terms of Service",
+                 "url": "https://example.org/somewhere/terms-1.2-en.html"
+             },
+             "fr": {
+                 "name": "Conditions d'utilisation",
+                 "url": "https://example.org/somewhere/terms-1.2-fr.html"
+             }
+           }
+         }
+       }
+     },
+     "session": "kasgjaelkgj"
+   }
+   ```
+
+3. The client presents the list of documents to the user, inviting them to
+   accept the polices.
+
+4. The client repeats the registration request, confirming that the user has
+   accepted the documents:
+   ```
+   POST /_matrix/client/v3/register
+   ```
+   ```json
+   {
+     "username": "cheeky_monkey",
+     "password": "ilovebananas",
+     "auth": {
+       "type": "m.login.terms",
+       "session": "kasgjaelkgj"
+     }
+   }
+   ```
+
+5. All authentication steps have now completed, so the request is successful:
+   ```
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+   ```
+   ```json
+   {
+     "access_token": "abc123",
+     "device_id": "GHTYAJCE",
+     "user_id": "@cheeky_monkey:matrix.org"
+   }
+   ```
+
+{{% definition path="api/client-server/definitions/m.login.terms_params" %}}
+
 #### Fallback
 
 Clients cannot be expected to be able to know how to process every
@@ -1118,7 +1314,7 @@ from.
 
 ### Login
 
-A client can obtain access tokens using the `/login` API.
+A client can obtain access tokens using the [`/login`](#post_matrixclientv3login) API.
 
 Note that this endpoint does <span class="title-ref">not</span>
 currently use the [User-Interactive Authentication
@@ -1176,8 +1372,8 @@ 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
+{{% added-in v="1.7" %}} Already-authenticated clients can additionally generate
-a token for their user ID if supported by the homeserver using 
+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" %}}
@@ -1234,7 +1430,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
@@ -1255,6 +1454,122 @@ number and a symbol and be at a minimum 8 characters in length. Servers
 MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 {{% /boxes/warning %}}
 
+#### Account locking
+
+{{% added-in v="1.12" %}}
+
+Server administrators may apply locks to prevent users from usefully
+using their accounts, for instance, due to safety or security concerns.
+In contrast to account deactivation, locking is a non-destructive action
+that can be reversed. This specification describes the behaviour of clients
+and servers when an account is locked. It deliberately leaves the methods
+for locking and unlocking accounts as a server implementation detail.
+
+When an account is locked, servers MUST return a `401 Unauthorized` error
+response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout)
+set to `true` on all but the following Client-Server APIs:
+
+- [`POST /logout`](#post_matrixclientv3logout)
+- [`POST /logout/all`](#post_matrixclientv3logoutall)
+
+Servers MAY additionally include details of why the lock was applied in
+the `error` field.
+
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
+
+```json
+{
+  "errcode": "M_USER_LOCKED",
+  "error": "This account has been locked",
+  "soft_logout": true
+}
+```
+
+Servers SHOULD NOT invalidate access tokens on locked accounts unless the
+client requests a logout (using the above endpoints). This ensures that
+users can retain their sessions without having to log back in if the account
+becomes unlocked.
+
+Upon receiving an `M_USER_LOCKED` error, clients SHOULD retain session
+information including encryption state and inform the user that their account
+has been locked. While the lock is applied, clients SHOULD hide the normal UI
+from the user, preventing general use of their account. Clients SHOULD, however,
+continue to make rate-limited requests to [`/sync`](#get_matrixclientv3sync)
+and other APIs to detect when the lock has been lifted.
+
+To enable users to appeal to a lock clients MAY use
+[server contact discovery](#getwell-knownmatrixsupport).
+
+#### Account suspension
+
+{{% added-in v="1.13" %}}
+
+Server administrators MAY suspend a user's account to prevent further activity
+from that account. The effect is similar to [locking](#account-locking), though
+without risk of the client losing state from a logout. Suspensions are reversible,
+like locks and unlike deactivations.
+
+The actions a user can perform while suspended is deliberately left as an
+implementation detail. Servers SHOULD permit the user to perform at least the
+following, however:
+
+* Log in and create additional sessions (which are also suspended).
+* See and receive messages, particularly through [`/sync`](#get_matrixclientv3sync)
+  and [`/messages`](#get_matrixclientv3roomsroomidmessages).
+* [Verify other devices](#device-verification) and write associated
+  [cross-signing data](#cross-signing).
+* [Populate their key backup](#server-side-key-backups).
+* [Leave rooms and reject invites](#post_matrixclientv3roomsroomidleave).
+* [Redact](#redactions) their own events.
+* [Log out](#post_matrixclientv3logout) or [delete](#delete_matrixclientv3devicesdeviceid)
+  any device of theirs, including the current session.
+* [Deactivate](#post_matrixclientv3accountdeactivate) their account, potentially
+  with a time delay to discourage making a new account right away.
+* Change or add [admin contacts](#adding-account-administrative-contact-information),
+  but not remove. Servers are recommended to only permit this if they keep a
+  changelog on contact information to prevent misuse.
+
+General purpose endpoints like [`/send/{eventType}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
+MAY return the error described below depending on the path parameters. For example,
+a user may be allowed to send `m.room.redaction` events but not `m.room.message`
+events through `/send`.
+
+Where a room is used to maintain communication between server administration
+teams and the suspended user, servers are recommended to allow the user to send
+events to that room specifically. Server administrators which do not want the
+user to continue receiving messages may be interested in [account locking](#account-locking)
+instead.
+
+Otherwise, the recommended set of explicitly forbidden actions is:
+
+* [Joining](#joining-rooms) or [knocking](#knocking-on-rooms) on rooms.
+* Accepting or sending [invites](#room-membership).
+* [Sending messages](#put_matrixclientv3roomsroomidsendeventtypetxnid) to rooms.
+* Changing [profile data](#profiles) (display name and avatar, primarily).
+* [Redacting](#redactions) other users' events, when permission is possible in a room.
+
+When a client attempts to perform an action while suspended, the server MUST
+respond with a `403 Forbidden` error response with `M_USER_SUSPENDED` as the
+error code, as shown below:
+
+```
+HTTP/1.1 403 Forbidden
+Content-Type: application/json
+```
+
+```json
+{
+  "errcode": "M_USER_SUSPENDED",
+  "error": "You cannot perform this action while suspended."
+}
+```
+
+APIs for initiating suspension or unsuspension are not included in this version
+of the specification, and left as an implementation detail.
+
 ### Adding Account Administrative Contact Information
 
 A homeserver may keep some contact information for administrative use.
@@ -1324,7 +1639,7 @@ The capabilities advertised through this system are intended to
 advertise functionality which is optional in the API, or which depend in
 some way on the state of the user or server. This system should not be
 used to advertise unstable or experimental features - this is better
-done by the `/versions` endpoint.
+done by the [`/versions`](#get_matrixclientversions) endpoint.
 
 Some examples of what a reasonable capability could be are:
 
@@ -1353,7 +1668,7 @@ specification are defined later in this section.
 ### `m.change_password` capability
 
 This capability has a single flag, `enabled`, which indicates whether or
-not the user can use the `/account/password` API to change their
+not the user can use the [`/account/password`](#post_matrixclientv3accountpassword) API to change their
 password. If not present, the client should assume that password changes
 are possible via the API. When present, clients SHOULD respect the
 capability's `enabled` flag and indicate to the user if they are unable
@@ -1484,6 +1799,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
@@ -1505,24 +1841,26 @@ events to the client to ease implementation, although such redundancy
 should be minimised where possible to conserve bandwidth.
 
 In terms of filters, lazy-loading is enabled by enabling
-`lazy_load_members` on a `RoomEventFilter` (or a `StateFilter` in the
+`lazy_load_members` on a
-case of `/sync` only). When enabled, lazy-loading aware endpoints (see
+[`RoomEventFilter`](#post_matrixclientv3useruseridfilter_request_roomeventfilter).
+When enabled, lazy-loading aware endpoints (see
 below) will only include membership events for the `sender` of events
 being included in the response. For example, if a client makes a `/sync`
 request with lazy-loading enabled, the server will only return
 membership events for the `sender` of events in the timeline, not all
 members of a room.
 
-When processing a sequence of events (e.g. by looping on `/sync` or
+When processing a sequence of events (e.g. by looping on
-paginating `/messages`), it is common for blocks of events in the
+[`/sync`](#get_matrixclientv3sync) or paginating
-sequence to share a similar set of senders. Rather than responses in the
+[`/messages`](#get_matrixclientv3roomsroomidmessages)), it is common for blocks
-sequence sending duplicate membership events for these senders to the
+of events in the sequence to share a similar set of senders. Rather than
-client, the server MAY assume that clients will remember membership
+responses in the sequence sending duplicate membership events for these senders
-events they have already been sent, and choose to skip sending
+to the client, the server MAY assume that clients will remember membership
-membership events for members whose membership has not changed. These
+events they have already been sent, and choose to skip sending membership
-are called 'redundant membership events'. Clients may request that
+events for members whose membership has not changed. These are called
-redundant membership events are always included in responses by setting
+'redundant membership events'. Clients may request that redundant membership
-`include_redundant_members` to true in the filter.
+events are always included in responses by setting `include_redundant_members`
+to true in the filter.
 
 The expected pattern for using lazy-loading is currently:
 
@@ -1537,7 +1875,7 @@ The expected pattern for using lazy-loading is currently:
     incremental /sync responses.
 -   Clients which do not support tab-completion may instead pull in
     profiles for arbitrary users (e.g. read receipts, typing
-    notifications) on demand by querying the room state or `/profile`.
+    notifications) on demand by querying the room state or [`/profile`](#get_matrixclientv3profileuserid).
 
 The current endpoints which support lazy-loading room members are:
 
@@ -1682,16 +2020,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
@@ -2096,11 +2433,11 @@ The endpoints where the server *should* include bundled aggregations are:
 * [`GET /sync`](#get_matrixclientv3sync) when the relevant section has a `limited` value
   of `true`.
 * [`POST /search`](#post_matrixclientv3search) for any matching events under `room_events`.
-* {{< added-in v="1.4" >}} [`GET /rooms/{roomId}/threads`](#get_matrixclientv1roomsroomidthreads)
+* {{% added-in v="1.4" %}} [`GET /rooms/{roomId}/threads`](#get_matrixclientv1roomsroomidthreads)
 
 {{% boxes/note %}}
 The server is **not** required to return bundled aggregations on deprecated endpoints
-such as `/initialSync`.
+such as [`/initialSync`](#get_matrixclientv3roomsroomidinitialsync).
 {{% /boxes/note %}}
 
 While this functionality allows the client to see what was known to the server at the
@@ -2156,6 +2493,19 @@ 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 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.
+
+Filters specified via `event_type` or `rel_type` will be applied to all events
+returned, whether direct or indirect relations. Events that would match the filter,
+but whose only relation to the original given event is through a non-matching
+intermediate event, will not be included. This means that supplying a `rel_type`
+parameter of `m.thread` is not appropriate for fetching all events in a thread since
+relations to the threaded events would be filtered out. For this purpose, clients should
+omit the `rel_type` parameter and perform any necessary filtering on the client side.
+
 {{% boxes/note %}}
 Because replies do not use `rel_type`, they will not be accessible via this API.
 {{% /boxes/note %}}
@@ -2309,7 +2659,7 @@ Note that this rule is only expected to work in room versions
 
 The allowable state transitions of membership are:
 
-![membership-flow-diagram](/diagrams/membership.png)
+{{% diagram name="membership" alt="Diagram presenting the possible membership state transitions" %}}
 
 {{% http-api spec="client-server" api="list_joined_rooms" %}}
 
@@ -2340,9 +2690,10 @@ this will have been just the API definition and nothing more (like invites).
 
 If the join rules allow, external users to the room can `/knock` on it to
 request permission to join. Users with appropriate permissions within the
-room can then approve (`/invite`) or deny (`/kick`, `/ban`, or otherwise
+room can then approve ([`/invite`](#post_matrixclientv3roomsroomidinvite))
+or deny ([`/kick`](#post_matrixclientv3roomsroomidkick), [`/ban`](#post_matrixclientv3roomsroomidban), or otherwise
 set membership to `leave`) the knock. Knocks can be retracted by calling
-`/leave` or otherwise setting membership to `leave`.
+[`/leave`](#post_matrixclientv3roomsroomidleave) or otherwise setting membership to `leave`.
 
 Users who are currently in the room, already invited, or banned cannot
 knock on the room.
@@ -2392,9 +2743,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.
 
@@ -2464,12 +2812,12 @@ with:
   "user_id": "<user id to ban>",
   "reason": "string: <reason for the ban>"
 }
-````
+```
 
 Banning a user adjusts the banned member's membership state to `ban`.
 Like with other membership changes, a user can directly adjust the
 target member's state, by making a request to
-`/rooms/<room id>/state/m.room.member/<user id>`:
+[`/rooms/<room id>/state/m.room.member/<user id>`](#put_matrixclientv3roomsroomidstateeventtypestatekey):
 
 ```json
 {
@@ -2497,7 +2845,25 @@ re-invited.
 
 {{% http-api spec="client-server" api="profile" %}}
 
-#### Events on Change of Profile Information
+#### Server behaviour
+
+Homeservers MUST at a minimum allow profile look-up for:
+
+-   users that share a room with the requesting user
+-   users that reside in public rooms known to the homeserver
+
+In all other cases, homeservers MAY deny profile look-up by responding with
+403 and an error code of `M_FORBIDDEN`.
+
+When a remote user is queried and the query is not denied per the above,
+homeservers SHOULD query the remote server for the user's profile information.
+The remote server MAY itself deny profile queries over federation, however.
+
+When the requested user does not exist, homeservers MAY choose whether to
+respond with 403 or 404. If the server denies profile look-up in all but the
+required cases, 403 is RECOMMENDED.
+
+##### Events on Change of Profile Information
 
 Because the profile display name and avatar information are likely to be
 used in many places of a client's display, changes to these fields cause
@@ -2521,25 +2887,6 @@ users, they should include the display name and avatar URL fields in
 these events so that clients already have these details to hand, and do
 not have to perform extra round trips to query it.
 
-## Security
-
-### Rate limiting
-
-Homeservers SHOULD implement rate limiting to reduce the risk of being
-overloaded. If a request is refused due to rate limiting, it should
-return a standard error response of the form:
-
-```json
-{
-  "errcode": "M_LIMIT_EXCEEDED",
-  "error": "string",
-  "retry_after_ms": integer (optional)
-}
-```
-
-The `retry_after_ms` key SHOULD be included to tell the client how long
-they have to wait in milliseconds before they can try again.
-
 ## Modules
 
 Modules are parts of the Client-Server API which are not universal to
@@ -2567,42 +2914,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.*
@@ -2651,42 +3001,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/account_data.md

@@ -16,7 +16,7 @@ data with the same `type`.
 The client receives the account data as events in the `account_data`
 sections of a [`/sync`](#get_matrixclientv3sync) response.
 
-These events can also be received in a `/events` response or in the
+These events can also be received in a [`/events`](#get_matrixclientv3events) response or in the
 `account_data` section of a room in a `/sync` response. `m.tag` events appearing in
 `/events` will have a `room_id` with the room the tags are for.
 
@@ -26,6 +26,15 @@ These events can also be received in a `/events` response or in the
 
 #### Server Behaviour
 
-Servers MUST reject clients from setting account data for event types
+Servers MUST reject setting account data for event types
-that the server manages. Currently, this only includes
+that the server manages by using a 405 error response.
-[m.fully\_read](#mfully_read).
+Currently, this only includes [`m.fully_read`](#mfully_read)
+and [`m.push_rules`](#push-rules-events). This applies to
+both global and room-specific account data.
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}} `m.push_rules` was added to the rejection
+list.
+{{% /boxes/note %}}
+
+Servers must allow clients to read the above event types as normal.

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

@@ -16,26 +16,69 @@ When serving content, the server SHOULD provide a
 `Content-Security-Policy` header. The recommended policy is
 `sandbox; default-src 'none'; script-src 'none'; plugin-types application/pdf; style-src 'unsafe-inline'; object-src 'self';`.
 
-{{% boxes/added-in-paragraph %}}
+{{% added-in v="1.4" %}} The server SHOULD additionally provide
-{{< added-in v="1.4" >}} The server SHOULD additionally provide
 `Cross-Origin-Resource-Policy: cross-origin` when serving content to allow
 (web) clients to access restricted APIs such as `SharedArrayBuffer` when
 interacting with the media repository.
-{{% /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.
 
 #### 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.
+
+{{% changed-in v="1.11" %}} A number of endpoints under the /_matrix/media hierarchy
+have been deprecated and replaced with new endpoints which require authentication.
+The deprecated endpoints are marked in the section below.
+
+{{% 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" %}}
 
@@ -119,3 +162,50 @@ Homeservers have additional content-specific concerns:
 -   Clients or remote homeservers may try to upload malicious files
     targeting vulnerabilities in either the homeserver thumbnailing or
     the client decoders.
+
+##### Serving inline content
+
+Clients with insecure configurations may be vulnerable to Cross-Site Scripting
+attacks when served media with a `Content-Disposition` of `inline`. Clients
+SHOULD NOT be hosted on the same domain as the media endpoints for the homeserver
+to mitigate most of this risk. Servers SHOULD restrict `Content-Type` headers to
+one of the following values when serving content with `Content-Disposition: inline`:
+
+* `text/css`
+* `text/plain`
+* `text/csv`
+* `application/json`
+* `application/ld+json`
+* `image/jpeg`
+* `image/gif`
+* `image/png`
+* `image/apng`
+* `image/webp`
+* `image/avif`
+* `video/mp4`
+* `video/webm`
+* `video/ogg`
+* `video/quicktime`
+* `audio/mp4`
+* `audio/webm`
+* `audio/aac`
+* `audio/mpeg`
+* `audio/ogg`
+* `audio/wave`
+* `audio/wav`
+* `audio/x-wav`
+* `audio/x-pn-wav`
+* `audio/flac`
+* `audio/x-flac`
+
+These types are unlikely to cause Cross-Site Scripting issues when a `Content-Type`
+header is provided, as clients will only try to render the data using that content
+type. For example, if a HTML file is uploaded with a `Content-Type` of `image/png`,
+clients will just assume that the image is corrupted, and won't render it as a
+HTML page. Therefore, there is no risk in trusting the user-defined content type,
+as long as the `Content-Disposition` is calculated based on that type.
+
+Clients SHOULD NOT rely on servers returning `inline` rather than `attachment`
+on [`/download`](#get_matrixclientv1mediadownloadservernamemediaid). Server implementations might decide out of an abundance of
+caution that all downloads are responded to with `attachment`, regardless of
+content type - clients should not be surprised by this behaviour.

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

@@ -77,6 +77,7 @@ algorithm is represented by an object with the following properties:
 |------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
 | key        | string     | **Required.** The unpadded Base64-encoded 32-byte Curve25519 public key.                                                                          |
 | signatures | Signatures | **Required.** Signatures of the key object. The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). |
+| fallback   | boolean    | Indicates whether this is a [fallback key](#one-time-and-fallback-keys). Defaults to `false`.                                                     |
 
 Example:
 
@@ -150,7 +151,9 @@ JSON](/appendices/#signing-json).
 
 One-time and fallback keys are also uploaded to the homeserver using the
 [`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) API. New
-one-time and fallback keys are uploaded as needed.
+one-time and fallback keys are uploaded as needed.  Fallback keys for key
+algorithms whose format is a signed JSON object should contain a property named
+`fallback` with a value of `true`.
 
 Devices must store the private part of each key they upload. They can
 discard the private part of a one-time key when they receive a message
@@ -657,10 +660,12 @@ The process between Alice and Bob verifying each other would be:
 11. Alice's device receives Bob's message and verifies the commitment
     hash from earlier matches the hash of the key Bob's device just sent
     and the content of Alice's `m.key.verification.start` message.
-12. Both Alice and Bob's devices perform an Elliptic-curve
+12. Both Alice's and Bob's devices perform an Elliptic-curve Diffie-Hellman using
-    Diffie-Hellman
+    their private ephemeral key, and the other device's ephemeral public key
-    (*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)),
+    (*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)
-    using the result as the shared secret.
+    for Alice's device and
+    *ECDH(K<sub>B</sub><sup>private</sup>*, *K<sub>A</sub><sup>public</sup>*)
+    for Bob's device), using the result as the shared secret.
 13. Both Alice and Bob's devices display a SAS to their users, which is
     derived from the shared key using one of the methods in this
     section. If multiple SAS methods are available, clients should allow
@@ -669,7 +674,7 @@ The process between Alice and Bob verifying each other would be:
     their devices if they match or not.
 15. Assuming they match, Alice and Bob's devices each calculate Message
     Authentication Codes (MACs) for:
-    * Each of the keys that they wish the other user to verify (usually their 
+    * Each of the keys that they wish the other user to verify (usually their
       device ed25519 key and their master cross-signing key).
     * The complete list of key IDs that they wish the other user to verify.
 
@@ -833,15 +838,15 @@ is the concatenation of:
 -   The Device ID of the device which sent the
     `m.key.verification.start` message, followed by `|`.
 -   The public key from the `m.key.verification.key` message sent by
-    the device which sent the `m.key.verification.start` message,
+    the device which sent the `m.key.verification.start` message, encoded as
-    followed by `|`.
+    unpadded base64, followed by `|`.
 -   The Matrix ID of the user who sent the `m.key.verification.accept`
     message, followed by `|`.
 -   The Device ID of the device which sent the
     `m.key.verification.accept` message, followed by `|`.
 -   The public key from the `m.key.verification.key` message sent by
-    the device which sent the `m.key.verification.accept` message,
+    the device which sent the `m.key.verification.accept` message, encoded as
-    followed by `|`.
+    unpadded base64, followed by `|`.
 -   The `transaction_id` being used.
 
 When the `key_agreement_protocol` is the deprecated method `curve25519`,
@@ -1174,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:
@@ -1189,22 +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 device 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 device key is
+  - if `0x01`, then what the device thinks the other device's Ed25519 signing
-  - if `0x02`, then what the device thinks the user's master cross-signing key
+    public key is
-    is
+  - if `0x02`, then what the device thinks the user's master cross-signing public
-- a random shared secret, as a byte string.  It is suggested to use a secret
+    key is
+- a random shared secret, as a sequence of bytes.  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
@@ -1266,10 +1278,10 @@ tries to read a message that it does not have keys for, it may request
 the key from the server and decrypt it. Backups are per-user, and users
 may replace backups with new backups.
 
-In contrast with [Key requests](#key-requests), Server-side key backups
+In contrast with [key requests](#key-requests), server-side key backups do not
-do not require another device to be online from which to request keys.
+require another device to be online from which to request keys. However, as
-However, as the session keys are stored on the server encrypted, it
+the session keys are stored on the server encrypted, the client requires a
-requires users to enter a decryption key to decrypt the session keys.
+[decryption key](#decryption-key) to decrypt the session keys.
 
 To create a backup, a client will call [POST
 /\_matrix/client/v3/room\_keys/version](#post_matrixclientv3room_keysversion) and define how the keys are to
@@ -1290,7 +1302,7 @@ Clients must only store keys in backups after they have ensured that the
 
 - checking that it is signed by the user's [master cross-signing
   key](#cross-signing) or by a verified device belonging to the same user, or
-- by deriving the public key from a private key that it obtained from a trusted
+- deriving the public key from a private key that it obtained from a trusted
   source. Trusted sources for the private key include the user entering the
   key, retrieving the key stored in [secret storage](#secret-storage), or
   obtaining the key via [secret sharing](#sharing) from a verified device
@@ -1307,31 +1319,24 @@ replace it with the new key based on the key metadata as follows:
 -   and finally, if `is_verified` and `first_message_index` are equal,
     then it will keep the key with a lower `forwarded_count`.
 
-###### Recovery key
+###### Decryption key
 
-If the recovery key (the private half of the backup encryption key) is
+Normally, the decryption key (i.e. the secret part of the encryption key) is
-presented to the user to save, it is presented as a string constructed
+stored on the server or shared with other devices using the [Secrets](#secrets)
-as follows:
+module. When doing so, it is identified using the name `m.megolm_backup.v1`,
+and the key is base64-encoded before being encrypted.
 
-1.  The 256-bit curve25519 private key is prepended by the bytes `0x8B`
+If the backup decryption key is given directly to the user, the key should be
-    and `0x01`
+presented as a string using the common [cryptographic key
-2.  All the bytes in the string above, including the two header bytes,
+representation](/appendices/#cryptographic-key-representation).
-    are XORed together to form a parity byte. This parity byte is
-    appended to the byte string.
-3.  The byte string is encoded using base58, using the same [mapping as
-    is used for Bitcoin
-    addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
-    that is, using the alphabet
-    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
-4.  A space should be added after every 4th character.
 
-When reading in a recovery key, clients must disregard whitespace, and
+{{% boxes/note %}}
-perform the reverse of steps 1 through 3.
+The backup decryption key was previously referred to as a "recovery
-
+key". However, this conflicted with common practice in client user
-The recovery key can also be stored on the server or shared with other devices
+interfaces, which often use the term "recovery key" to refer to the [secret
-using the [Secrets](#secrets) module. When doing so, it is identified using the
+storage](#storage) key. The term "recovery key" is no longer used in this
-name `m.megolm_backup.v1`, and the key is base64-encoded before being
+specification.
-encrypted.
+{{% /boxes/note %}}
 
 ###### Backup algorithm: `m.megolm_backup.v1.curve25519-aes-sha2`
 
@@ -1344,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
@@ -1361,10 +1366,18 @@ The `session_data` field in the backups is constructed as follows:
     PKCS\#7 padding. This encrypted data, encoded using unpadded base64,
     becomes the `ciphertext` property of the `session_data`.
 
-5.  Pass the raw encrypted data (prior to base64 encoding) through
+5.  Pass an empty string through HMAC-SHA-256 using the MAC key generated above.
-    HMAC-SHA-256 using the MAC key generated above. The first 8 bytes of
+    The first 8 bytes of the resulting MAC are base64-encoded, and become the
-    the resulting MAC are base64-encoded, and become the `mac` property
+    `mac` property of the `session_data`.
-    of the `session_data`.
+
+{{% boxes/warning %}}
+Step 5 was intended to pass the raw encrypted data, but due to a bug in libolm,
+all implementations have since passed an empty string instead.
+
+Future versions of the spec will fix this problem. See
+[MSC4048](https://github.com/matrix-org/matrix-spec-proposals/pull/4048) for a
+potential new key backup algorithm version that would fix this issue.
+{{% /boxes/warning %}}
 
 {{% definition path="api/client-server/definitions/key_backup_session_data" %}}
 
@@ -1414,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" %}}
@@ -1523,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
@@ -1765,9 +1780,9 @@ Example response:
     ],
   },
   "device_one_time_keys_count": {
-    "curve25519": 10,
     "signed_curve25519": 20
-  }
+  },
+  "device_unused_fallback_key_types": ["signed_curve25519"]
 }
 ```
 

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

@@ -14,7 +14,7 @@ event with the corresponding emoji (👍). Another potential usage is to allow
 bots to send an event indicating the success or failure of a command.
 
 Along with the normal properties `event_id` and `rel_type`, an `m.relates_to`
-property with `rel_type: m.annotion` should contain a `key` that indicates the
+property with `rel_type: m.annotation` should contain a `key` that indicates the
 annotation being applied. For example, when reacting with emojis, the key
 contains the emoji being used.
 

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

@@ -188,7 +188,7 @@ replacement event.
 
 ##### Server-side aggregation of `m.replace` relationships
 
-{{< changed-in v="1.7" >}}
+{{% changed-in v="1.7" %}}
 
 Note that there can be multiple events with an `m.replace` relationship to a
 given event (for example, if an event is edited multiple times). These should
@@ -309,7 +309,7 @@ for re-notifying if the sending client feels a large enough revision was made).
 
 For example, if there is an event mentioning Alice:
 
-```json5
+```json
 {
     "event_id": "$original_event",
     "type": "m.room.message",
@@ -324,7 +324,7 @@ For example, if there is an event mentioning Alice:
 
 And an edit to also mention Bob:
 
-```json5
+```json
 {
   "content": {
     "body": "* Hello Alice & Bob!",
@@ -362,21 +362,19 @@ property under `m.new_content`.
 
 #### Edits of replies
 
-Some particular constraints apply to events which replace a
+A particular constraint applies to events which replace a [reply](#rich-replies):
-[reply](#rich-replies). In particular:
+in contrast to the original reply, there should be no `m.in_reply_to` property
+in the the `m.relates_to` object, since it would be redundant (see
+[Applying `m.new_content`](#applying-mnew_content) above, which notes that the
+original event's `m.relates_to` is preserved), as well as being contrary to the
+spirit of the event relationships mechanism which expects only one "parent" per
+event.
 
- * In contrast to the original reply, there should be no `m.in_reply_to`
+{{% boxes/note %}}
-   property in the the `m.relates_to` object, since it would be redundant (see
+{{% changed-in v="1.13" %}}
-   [Applying `m.new_content`](#applying-mnew_content) above, which notes that
+In previous versions of the specification, events which replace a [reply](#rich-replies)
-   the original event's `m.relates_to` is preserved), as well as being contrary
+could include a fallback in the `content`. This is no longer the case.
-   to the spirit of the event relationships mechanism which expects only one
+{{% /boxes/note %}}
-   "parent" per event.
-
- * `m.new_content` should **not** contain any [reply
-   fallback](#fallbacks-for-rich-replies),
-   since it is assumed that any client which can handle edits can also display
-   replies natively. However, the `content` of the replacement event should provide
-   fallback content for clients which support neither rich replies nor edits.
 
 An example of an edit to a reply is as follows:
 
@@ -385,15 +383,11 @@ An example of an edit to a reply is as follows:
   "type": "m.room.message",
   // irrelevant fields not shown
   "content": {
-    "body": "> <@alice:example.org> question\n\n* reply",
+    "body": "* reply",
     "msgtype": "m.text",
-    "format": "org.matrix.custom.html",
-    "formatted_body": "<mx-reply><blockquote><a href=\"https://matrix.to/#/!somewhere:example.org/$event:example.org\">In reply to</a> <a href=\"https://matrix.to/#/@alice:example.org\">@alice:example.org</a><br />question</blockquote></mx-reply>* reply",
     "m.new_content": {
       "body": "reply",
       "msgtype": "m.text",
-      "format": "org.matrix.custom.html",
-      "formatted_body": "reply"
     },
     "m.relates_to": {
       "rel_type": "m.replace",

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

@@ -33,17 +33,20 @@ rather than allowing all homeservers to enforce the rules on each other.
 #### Client behaviour
 
 The following API endpoints are allowed to be accessed by guest accounts
-for retrieving events:
+for retrieving events and associated media:
 
 * [GET /rooms/{roomId}/state](#get_matrixclientv3roomsroomidstate)
 * [GET /rooms/{roomId}/context/{eventId}](#get_matrixclientv3roomsroomidcontexteventid)
 * [GET /rooms/{roomId}/event/{eventId}](#get_matrixclientv3roomsroomideventeventid)
 * [GET /rooms/{roomId}/state/{eventType}/{stateKey}](#get_matrixclientv3roomsroomidstateeventtypestatekey)
 * [GET /rooms/{roomId}/messages](#get_matrixclientv3roomsroomidmessages)
-* {{< added-in v="1.1" >}} [GET /rooms/{roomId}/members](#get_matrixclientv3roomsroomidmembers)
+* {{% added-in v="1.1" %}} [GET /rooms/{roomId}/members](#get_matrixclientv3roomsroomidmembers)
 * [GET /rooms/{roomId}/initialSync](#get_matrixclientv3roomsroomidinitialsync)
 * [GET /sync](#get_matrixclientv3sync)
 * [GET /events](#get_matrixclientv3events) as used for room previews.
+* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid)
+* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename)
+* {{% added-in v="1.12" %}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid)
 
 The following API endpoints are allowed to be accessed by guest accounts
 for sending events:
@@ -52,9 +55,9 @@ for sending events:
 * [POST /rooms/{roomId}/leave](#post_matrixclientv3roomsroomidleave)
 * [PUT /rooms/{roomId}/send/{eventType}/{txnId}](#put_matrixclientv3roomsroomidsendeventtypetxnid)
 
-    * {{< changed-in v="1.2" >}} Guests can now send *any* event type rather than just `m.room.message` events.
+    * {{% changed-in v="1.2" %}} Guests can now send *any* event type rather than just `m.room.message` events.
 
-* {{< added-in v="1.2" >}} [PUT /rooms/{roomId}/state/{eventType}/{stateKey}](#put_matrixclientv3roomsroomidstateeventtypestatekey)
+* {{% added-in v="1.2" %}} [PUT /rooms/{roomId}/state/{eventType}/{stateKey}](#put_matrixclientv3roomsroomidstateeventtypestatekey)
 * [PUT /sendToDevice/{eventType}/{txnId}](#put_matrixclientv3sendtodeviceeventtypetxnid)
 
 The following API endpoints are allowed to be accessed by guest accounts
@@ -64,7 +67,7 @@ for their own account maintenance:
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)
-* {{< added-in v="1.2" >}} [GET /account/whoami](#get_matrixclientv3accountwhoami)
+* {{% added-in v="1.2" %}} [GET /account/whoami](#get_matrixclientv3accountwhoami)
 
 The following API endpoints are allowed to be accessed by guest accounts
 for end-to-end encryption:

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

@@ -13,10 +13,10 @@ and servers can implement the ignoring of users.
 
 To ignore a user, effectively blocking them, the client should add the
 target user to the `m.ignored_user_list` event in their account data
-using [`/user/<user_id>/account_data/<type>`](/client-server-api/#put_matrixclientv3useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by
+using [`/user/<user_id>/account_data/<type>`](#put_matrixclientv3useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by
 that user, with the exception of state events. The client should either
 hide previous content sent by the newly ignored user or perform a new
-`/sync` with no previous token.
+[`/sync`](#get_matrixclientv3sync) with no previous token.
 
 Invites to new rooms by ignored users will not be sent to the client.
 The server may optionally reject the invite on behalf of the client.

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

@@ -27,18 +27,41 @@ instead.
 
 Some message types support HTML in the event content that clients should
 prefer to display if available. Currently `m.text`, `m.emote`, `m.notice`,
-and `m.key.verification.request` support an additional `format` parameter of
+`m.image`, `m.file`, `m.audio`, `m.video` and `m.key.verification.request`
-`org.matrix.custom.html`. When this field is present, a `formatted_body`
+support an additional `format` parameter of `org.matrix.custom.html`. When this
-with the HTML must be provided. The plain text version of the HTML
+field is present, a `formatted_body` with the HTML must be provided. The plain
-should be provided in the `body`.
+text version of the HTML should be provided in the `body`.
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}}
+In previous versions of the specification, the `format` and `formatted` fields
+were limited to `m.text`, `m.emote`, `m.notice`, and
+`m.key.verification.request`. This list is expanded to include `m.image`,
+`m.file`, `m.audio` and `m.video` for [media captions](#media-captions).
+{{% /boxes/note %}}
 
 Clients should limit the HTML they render to avoid Cross-Site Scripting,
 HTML injection, and similar attacks. The strongly suggested set of HTML
 tags to permit, denying the use and rendering of anything else, is:
-`font`, `del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`,
+`del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`, `a`, `ul`,
-`a`, `ul`, `ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`,
+`ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`, `s`, `code`,
-`strike`, `code`, `hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`,
+`hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`, `th`, `td`,
-`th`, `td`, `caption`, `pre`, `span`, `img`, `details`, `summary`.
+`caption`, `pre`, `span`, `img`, `details`, `summary`.
+
+{{% boxes/note %}}
+{{% added-in v="1.10" %}}
+HTML features MAY be deprecated and replaced by their modern equivalent without
+requiring a [Spec Change Proposal](/proposals) when they are deprecated in the
+[WHATWG HTML Living Standard](https://html.spec.whatwg.org/multipage/).
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}}
+In previous versions of the specification, the `font` tag was suggested with the
+`data-mx-bg-color`, `data-mx-color` and `color` attributes. This tag is now
+deprecated in favor of the `span` tag with the `data-mx-bg-color` and
+`data-mx-color` attributes in new messages.
+{{% /boxes/note %}}
 
 Not all attributes on those tags should be permitted as they may be
 avenues for other disruption attempts, such as adding `onclick` handlers
@@ -50,12 +73,12 @@ the tag.
 
 | Tag    | Permitted Attributes                                                                                                                       |
 |--------|--------------------------------------------------------------------------------------------------------------------------------------------|
-| `font` | `data-mx-bg-color`, `data-mx-color`, `color`                                                                                               |
+| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)), `data-mx-maths` (see [mathematical messages](#mathematical-messages)) |
-| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages))                                         |
+| `a`    | `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`)         |
-| `a`    | `name`, `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)                                                                |
+| `div` | `data-mx-maths` (see [mathematical messages](#mathematical-messages))                                                                      |
 
 Additionally, web clients should ensure that *all* `a` tags get a
 `rel="noopener"` to prevent the target page from referencing the
@@ -75,14 +98,12 @@ having appropriate closing tags, appropriate attributes (considering the
 custom ones defined in this specification), and generally valid
 structure.
 
-A special tag, `mx-reply`, may appear on rich replies (described below)
+{{% boxes/note %}}
-and should be allowed if, and only if, the tag appears as the very first
+{{% changed-in v="1.13" %}}
-tag in the `formatted_body`. The tag cannot be nested and cannot be
+In previous versions of the specification, [rich replies](#rich-replies) could
-located after another tag in the tree. Because the tag contains HTML, an
+use a special tag, `mx-reply`. This is no longer the case. Clients SHOULD strip
-`mx-reply` is expected to have a partner closing tag and should be
+this tag and its content. See the "Rich replies" section for more information.
-treated similar to a `div`. Clients that support rich replies will end
+{{% /boxes/note %}}
-up stripping the tag and its contents and therefore may wish to exclude
-the tag entirely.
 
 {{% boxes/note %}}
 A future iteration of the specification will support more powerful and
@@ -320,6 +341,107 @@ to the media repository, then reference the `mxc://` URI in a markdown-style lin
 Clients SHOULD render spoilers differently with some sort of disclosure. For example, the
 client could blur the actual text and ask the user to click on it for it to be revealed.
 
+##### Media captions
+
+{{% added-in v="1.10" %}}
+
+Media messages, comprised of `m.image`, `m.file`, `m.audio` and `m.video`, can
+include a caption to convey additional information about the media.
+
+To send captions, clients MUST use the `filename` and the `body`, and optionally
+the `formatted_body` with the `org.matrix.custom.html` format, described above.
+
+If the `filename` is present, and its value is different than `body`, then
+`body` is considered to be a caption, otherwise `body` is a filename. `format`
+and `formatted_body` are only used for captions.
+
+{{% boxes/note %}}
+In previous versions of the specification, `body` was usually used to set the
+filename of the uploaded file, and `filename` was only present on `m.file` with
+the same purpose.
+{{% /boxes/note %}}
+
+An example of a media message with a caption is:
+
+```json
+{
+    "msgtype": "m.image",
+    "url": "mxc://example.org/abc123",
+    "filename": "dog.jpg",
+    "body": "this is a ~~cat~~ picture :3",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "this is a <s>cat</s> picture :3",
+    "info": {
+        "w": 479,
+        "h": 640,
+        "mimetype": "image/jpeg",
+        "size": 27253
+    },
+    "m.mentions": {}
+}
+```
+
+Clients MUST render the caption alongside the media and SHOULD prefer its
+formatted representation.
+
+##### Mathematical messages
+
+{{% added-in v="1.11" %}}
+
+Users might want to send mathematical notations in their messages.
+
+To send mathematical notations clients MUST use the `formatted_body` and
+therefore the `org.matrix.custom.html` format, described above. This makes
+mathematical notations valid on any `msgtype` which can support this format
+appropriately.
+
+Mathematical notations themselves use the `span` or `div` tags, depending
+whether the notation should be presented inline or not. The mathematical
+notation is written in [LaTeX](https://www.latex-project.org/) format using the
+`data-mx-maths` attribute.
+
+The contents of the tag should be a fallback representation for clients that
+cannot render the LaTeX format. The fallback representation could be, for
+example, an image, or an HTML approximation, or the raw LaTeX source. When using
+an image as a fallback, the sending client should be aware of issues that may
+arise from the receiving client using a different background colour. The `body`
+should include a textual representation of the notation.
+
+An example of a mathematical notation is:
+
+```json
+{
+  "msgtype": "m.text",
+  "format": "org.matrix.custom.html",
+  "body": "This is an equation: sin(x)=a/b.",
+  "formatted_body": "This is an equation:
+      <span data-mx-maths=\"\\sin(x)=\\frac{a}{b}\">
+        sin(<i>x</i>)=<sup><i>a</i></sup>/<sub><i>b</i></sub>
+      </span>"
+}
+```
+
+The LaTeX format is poorly defined and has several extensions, so if a client
+encounters syntax that it cannot render, it SHOULD present the fallback
+representation instead. Clients SHOULD, however, aim to support, at minimum, the
+basic [LaTeX2e](https://www.latex-project.org/) maths commands and the
+[TeX](https://tug.org/) maths commands, with the possible exception of commands
+that could be security risks.
+
+{{% boxes/warning %}}
+In general, LaTeX places a heavy burden on client authors to ensure that it is
+processed safely. Certain commands, such as [those that can create macros](https://katex.org/docs/supported#macros),
+are potentially dangerous. Clients should either decline to process those
+commands, or should take care to ensure that they are handled in safe ways (such
+as by limiting recursion). In general, LaTeX commands should be filtered by
+allowing known-good commands rather than forbidding known-bad commands.
+
+Therefore, clients should not render mathematics by calling a LaTeX compiler
+without proper sandboxing, as those executables were not written to handle
+untrusted input. Some LaTeX rendering libraries are better suited for that by
+allowing only a subset of LaTeX and enforcing recursion limits.
+{{% /boxes/warning %}}
+
 #### Server behaviour
 
 Homeservers SHOULD reject `m.room.message` events which don't have a

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

@@ -13,6 +13,20 @@ the event to reference the entity being mentioned.
 
 {{% definition path="api/client-server/definitions/m.mentions" %}}
 
+An event's content will then look like this:
+
+```json
+{
+    "body": "Hello Alice!",
+    "msgtype": "m.text",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
+    "m.mentions": {
+        "user_ids": ["@alice:example.org"]
+    }
+}
+```
+
 Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
 [`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
 Users should not add their own Matrix ID to the `m.mentions` property as outgoing

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

@@ -13,7 +13,7 @@ deciding what content is undesirable for any particular entity and
 should instead be empowering those entities to make their own decisions.
 As such, a generic framework for communicating "moderation policy lists"
 or "moderation policy rooms" is described. Note that this module only
-describes the data structures and not how they should be interpreting:
+describes the data structures and not how they should be interpreted:
 the entity making the decisions on filtering is best positioned to
 interpret the rules how it sees fit.
 

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
 
@@ -454,7 +456,7 @@ Definition:
         {
             "kind": "event_match",
             "key": "content.msgtype",
-            "pattern": "m.notice",
+            "pattern": "m.notice"
         }
     ],
     "actions": []
@@ -521,9 +523,9 @@ 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" >}}
+{{% 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.
@@ -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,9 +592,9 @@ 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" >}}
+{{% 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`.
@@ -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" %}}
 
@@ -750,9 +752,33 @@ Definition:
 }
 ```
 
+**`.m.rule.suppress_edits`**
+
+{{% added-in v="1.9" %}}
+
+Suppresses notifications related to [event replacements](#event-replacements).
+
+Definition:
+
+```json
+{
+    "rule_id": ".m.rule.suppress_edits",
+    "default": true,
+    "enabled": true,
+    "conditions": [
+        {
+            "kind": "event_property_is",
+            "key": "content.m\\.relates_to.rel_type",
+            "value": "m.replace"
+        }
+    ],
+    "actions": []
+}
+```
+
 ##### 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" %}}
 
@@ -1018,7 +1044,7 @@ messages they have received.
 ##### Receiving notifications
 
 Servers MUST include the number of unread notifications in a client's
-`/sync` stream, and MUST update it as it changes. Notifications are
+[`/sync`](#get_matrixclientv3sync) stream, and MUST update it as it changes. Notifications are
 determined by the push rules which apply to an event.
 
 For encrypted events, the homeserver has limited access to the event content
@@ -1046,16 +1072,16 @@ ahead), however if the `m.read.private` receipt were to be updated to
 event D then the user has read up to D (the `m.read` receipt is now
 behind the `m.read.private` receipt).
 
-{{< added-in v="1.4" >}} When handling threaded read receipts, the server
+{{% added-in v="1.4" %}} When handling threaded read receipts, the server is to
-is to partition the notification count to each thread (with the main timeline
+partition the notification count to each thread (with the main timeline being
-being its own thread). To determine if an event is part of a thread the
+its own thread). To determine if an event is part of a thread the server follows
-server follows the [event relationship](#forming-relationships-between-events)
+the [event relationship](#forming-relationships-between-events) until it finds a
-until it finds a thread root (as specified by the [threading module](#threading)),
+thread root via an `m.thread` relation (as specified by the [threading
-however it is not recommended that the server traverse infinitely. Instead,
+module](#threading)), however it is not recommended that the server traverse
-implementations are encouraged to do a maximum of 3 hops to find a thread
+infinitely. Instead, implementations are encouraged to do a maximum of 3 hops to
-before deciding that the event does not belong to a thread. This is primarily
+find a thread before deciding that the event does not belong to a thread. This
-to ensure that future events, like `m.reaction`, are correctly considered
+is primarily to ensure that future events, like `m.reaction`, are correctly
-"part of" a given thread.
+considered "part of" a given thread.
 
 #### Server behaviour
 
@@ -1065,7 +1091,7 @@ users in the room (excluding the sender). This may result in:
 * Generating a new number of unread notifications for the user.
 * Making a request to the configured push gateway.
 
-The updated notification count from a new event MUST appear in the same `/sync`
+The updated notification count from a new event MUST appear in the same [`/sync`](#get_matrixclientv3sync)
 response as the event itself.
 
 #### Push Gateway behaviour

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,13 +23,13 @@ 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
 the read markers API to change the values.
 
-{{< changed-in v="1.4" >}} `m.read.private` receipts can now be sent from
+{{% changed-in v="1.4" %}} `m.read.private` receipts can now be sent from
 `/read_markers`.
 
 The read markers API can additionally update the user's read receipt
@@ -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,46 @@ 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
+
+{{% added-in v="1.12" %}}
+
+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/receipts.md

@@ -1,7 +1,7 @@
 
 ### Receipts
 
-{{< changed-in v="1.4" >}} Added private read receipts.
+{{% changed-in v="1.4" %}} Added private read receipts.
 
 This module adds in support for receipts. These receipts are a form of
 acknowledgement of an event. This module defines the `m.read` receipt
@@ -19,7 +19,7 @@ that the user had read all events *up to* the referenced event. See the
 [Receiving notifications](#receiving-notifications) section for more
 information on how read receipts affect notification counts.
 
-{{< added-in v="1.4" >}} Read receipts exist in three major forms:
+{{% added-in v="1.4" %}} Read receipts exist in three major forms:
 * Unthreaded: Denotes a read-up-to receipt regardless of threads. This is how
   pre-threading read receipts worked.
 * Threaded, main timeline: Denotes a read-up-to receipt for events not in a
@@ -31,7 +31,7 @@ Threaded read receipts are discussed in further detail [below](#threaded-read-re
 
 #### Events
 
-{{< changed-in v="1.4" >}} Each `user_id`, `receipt_type`, and categorisation
+{{% changed-in v="1.4" %}} Each `user_id`, `receipt_type`, and categorisation
 (unthreaded, or `thread_id`) tuple must be associated with only a single
 `event_id`.
 
@@ -39,9 +39,9 @@ Threaded read receipts are discussed in further detail [below](#threaded-read-re
 
 #### Client behaviour
 
-{{< changed-in v="1.4" >}} Altered to support threaded read receipts.
+{{% changed-in v="1.4" %}} Altered to support threaded read receipts.
 
-In `/sync`, receipts are listed under the `ephemeral` array of events
+In [`/sync`](#get_matrixclientv3sync), receipts are listed under the `ephemeral` array of events
 for a given room. New receipts that come down the event streams are
 deltas which update existing mappings. Clients should replace older
 receipt acknowledgements based on `user_id`, `receipt_type`, and the
@@ -137,26 +137,30 @@ either a thread root's event ID or `main` for the main timeline.
 
 Threading introduces a concept of multiple conversations being held in the same
 room and thus deserve their own read receipts and notification counts. An event is
-considered to be "in a thread" if it meets any of the following criteria:
+considered to be "in a thread" if:
-* It has a `rel_type` of `m.thread`.
-* It has child events with a `rel_type` of `m.thread` (in which case it'd be the
-  thread root).
-* Following the event relationships, it has a parent event which qualifies for
-  one of the above. Implementations should not recurse infinitely, though: a
-  maximum of 3 hops is recommended to cover indirect relationships.
 
-Events not in a thread but still in the room are considered to be part of the
+* It has a `rel_type` of `m.thread`, or
-"main timeline", or a special thread with an ID of `main`.
+* Following the event relationships, it has a parent event which references
+  the thread root with a `rel_type` of `m.thread`. Implementations should
+  not recurse infinitely, though: a maximum of 3 hops is recommended to
+  cover indirect relationships.
+
+Events not in a thread but still in the room are considered to be in the "main
+timeline". When referring to the main timeline as a thread (e.g. in receipts
+and notifications counts) a special thread ID of `main` is used.
+
+Thread roots are considered to be in the main timeline, as are events that are
+related to a thread root via non-thread relations.
 
 The following is an example DAG for a room, with dotted lines showing event
 relationships and solid lines showing topological ordering.
 
-![threaded-dag](/diagrams/threaded-dag.png)
+{{% diagram name="threaded-dag" alt="Diagram presenting a DAG with thread relationships as a single timeline" %}}
 
 This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread
 roots:
 
-![threaded-dag-threads](/diagrams/threaded-dag-threads.png)
+{{% diagram name="threaded-dag-threads" alt="Diagram presenting a DAG with thread relationships as 3 related timelines" %}}
 
 With this, we can demonstrate that:
 * A threaded read receipt on `I` would mark `A`, `B`, and `I` as read.
@@ -204,7 +208,7 @@ event when the user expands that thread.
 
 #### Server behaviour
 
-For efficiency, receipts SHOULD be batched into one event per room
+For efficiency, receipts SHOULD be batched into one event per room and thread
 before delivering them to clients.
 
 Some receipts are sent across federation as EDUs with type `m.receipt`. The

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

@@ -5,9 +5,6 @@ Users may encounter content which they find inappropriate and should be
 able to report it to the server administrators or room moderators for
 review. This module defines a way for users to report content.
 
-Content is reported based upon a negative score, where -100 is "most
-offensive" and 0 is "inoffensive".
-
 #### Client behaviour
 
 {{% http-api spec="client-server" api="report_content" %}}
@@ -18,3 +15,17 @@ Servers are free to handle the reported content however they desire.
 This may be a dedicated room to alert server administrators to the
 reported content or some other mechanism for notifying the appropriate
 people.
+
+Particularly during waves of harmful content, users may report whole
+rooms instead of individual events. Server administrators and safety teams
+should, therefore, be cautious not to shut down rooms that might otherwise
+be legitimate.
+
+{{% changed-in v="1.8" %}} When processing event reports, servers MUST
+verify that the reporting user is currently joined to the room the event
+is in before accepting a report.
+
+{{% added-in v="1.13" %}} Contrarily, servers MUST NOT restrict room reports
+based on whether or not the reporting user is joined to the room. This is
+because users can be exposed to harmful content without being joined to a
+room. For instance, through room directories or invites.