Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-18 03:53:43 +01:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'main' into reduce-table-margin

Browse source
This commit is contained in:
Richard van der Hoff 2025-04-15 18:26:52 +01:00 committed by GitHub
parent e4fc47ece1 65b1db721d
commit 10a0d1bc1b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
82 changed files with 859 additions and 702 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/appendices/newsfragments/1506.clarification
View file

@ -1 +0,0 @@
Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.

1
changelogs/client_server/newsfragments/2036.clarification
View file

@ -1 +0,0 @@
The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking.

1
changelogs/client_server/newsfragments/2038.clarification
View file

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

1
changelogs/client_server/newsfragments/2046.clarification
View file

@ -1 +0,0 @@
Clarify formats of string types.

2
changelogs/client_server/newsfragments/2051.clarification
View file

@ -1,2 +0,0 @@
Document the `instance_id` field of `Protocol Instance` in the responses to
`GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.

1
changelogs/client_server/newsfragments/2055.clarification
View file

@ -1 +0,0 @@
Applying redactions is a SHOULD for clients.

1
changelogs/client_server/newsfragments/2059.removal
View file

@ -1 +0,0 @@
Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213).

1
changelogs/client_server/newsfragments/2064.clarification
View file

@ -1 +0,0 @@
Clarify which rooms are returned from `/hierarchy`.

1
changelogs/client_server/newsfragments/2068.clarification Normal file
View file

@ -0,0 +1 @@
Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.

1
changelogs/client_server/newsfragments/2077.clarification Normal file
View file

@ -0,0 +1 @@
Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.

0
changelogs/client_server/newsfragments/2047.clarification → changelogs/client_server/newsfragments/2121.clarification
View file

1
changelogs/internal/newsfragments/2033.clarification
View file

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

1
changelogs/internal/newsfragments/2041.clarification
View file

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

1
changelogs/internal/newsfragments/2042.clarification
View file

@ -1 +0,0 @@
Remove unused `release_date` from Hugo config.

1
changelogs/internal/newsfragments/2045.clarification
View file

@ -1 +0,0 @@
Clarify that v1.0 of Matrix was a release prior to the current global versioning system.

1
changelogs/internal/newsfragments/2049.clarification
View file

@ -1 +0,0 @@
Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS.

1
changelogs/internal/newsfragments/2061.clarification
View file

@ -1 +0,0 @@
Fix the version of the Identity Service API when Matrix 1.0 was introduced.

1
changelogs/internal/newsfragments/2115.clarification Normal file
View file

@ -0,0 +1 @@
Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.

1
changelogs/room_versions/newsfragments/2066.clarification
View file

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

1
changelogs/server_server/newsfragments/2050.clarification
View file

@ -1 +0,0 @@
Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.

0
changelogs/client_server/newsfragments/2048.clarification → changelogs/server_server/newsfragments/2128.clarification
View file

2
config/_default/hugo.toml
View file

@ -67,7 +67,7 @@ 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 # The following is used when status = "stable", and is displayed in various UI elements on a released version
# of the spec. # of the spec.
# major = "1" # major = "1"
# minor = "13" # minor = "14"
# User interface configuration # User interface configuration
[params.ui] [params.ui]

93
content/changelog/v1.14.md Normal file
View file

@ -0,0 +1,93 @@
---
title: v1.14 Changelog
linkTitle: v1.14
type: docs
layout: changelog
outputs:
- html
- checklist
date: 2025-03-27
---
## Client-Server API
**New Endpoints**
- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093))
**Removed Endpoints**
- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059))
**Spec Clarifications**
- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036))
- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038))
- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046))
- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091))
- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051))
- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055))
- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064))
- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072))
## Server-Server API
**Spec Clarifications**
- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050))
- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063))
- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
## Application Service API
No significant changes.
## Identity Service API
No significant changes.
## Push Gateway API
No significant changes.
## Room Versions
**Backwards Compatible Changes**
- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105))
**Spec Clarifications**
- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
## Appendices
**Spec Clarifications**
- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506))
## Internal Changes/Tooling
**Spec Clarifications**
- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033))
- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041))
- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042))
- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045))
- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049))
- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061))
- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069))
- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073))
- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074))
- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078))

7
content/client-server-api/modules/history_visibility.md
View file

@ -43,11 +43,8 @@ setting at that time was more restrictive.
#### Client behaviour #### Client behaviour
Clients that implement this module MUST present to the user the possible Clients may want to display a notice that events may be read by
options for setting history visibility when creating a room. non-joined people if the history visibility is set to `world_readable`.
Clients may want to display a notice that their events may be read by
non-joined people if the value is set to `world_readable`.
#### Server behaviour #### Server behaviour

6
content/client-server-api/modules/report_content.md
View file

@ -29,3 +29,9 @@ is in before accepting a report.
based on whether or not the reporting user is joined to the room. This is 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 because users can be exposed to harmful content without being joined to a
room. For instance, through room directories or invites. room. For instance, through room directories or invites.
{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports
based on whether or not the reporting user is joined to any rooms that the
reported user is joined to. This is because users can be exposed to harmful
content without being joined to a room. For instance, through user
directories or invites.

2
content/client-server-api/modules/secrets.md
View file

@ -58,7 +58,7 @@ available on all their clients. Unless the user specifies otherwise,
clients will try to use the default key to decrypt secrets. clients will try to use the default key to decrypt secrets.
Clients that want to present a simplified interface to users by not supporting Clients that want to present a simplified interface to users by not supporting
multiple keys should use the default key if one is specified. If not default multiple keys should use the default key if one is specified. If no default
key is specified, the client may behave as if there is no key is present at key is specified, the client may behave as if there is no key is present at
all. When such a client creates a key, it should mark that key as being the all. When such a client creates a key, it should mark that key as being the
default key. default key.

2
content/rooms/_index.md
View file

@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including
discovered security vulnerabilities and age. discovered security vulnerabilities and age.
Clients should not ask room administrators to upgrade their rooms if the Clients should not ask room administrators to upgrade their rooms if the
room is running a stable version. Servers SHOULD use **room version 10** as room is running a stable version. Servers SHOULD use **room version 11** as
the default room version when creating new rooms. the default room version when creating new rooms.
The available room versions are: The available room versions are:

4
content/rooms/fragments/v6-event-format.md Normal file
View file

@ -0,0 +1,4 @@
Events in rooms of this version have the following structure:
{{% definition path="api/server-server/definitions/pdu_v6" %}}

2
content/rooms/v1.md
View file

@ -51,7 +51,7 @@ inconsistencies may occur.
Events in version 1 rooms have the following structure: Events in version 1 rooms have the following structure:
{{% definition path="api/server-server/definitions/pdu" %}} {{% definition path="api/server-server/definitions/pdu_v1" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

2
content/rooms/v10.md
View file

@ -281,7 +281,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
### State resolution ### State resolution

2
content/rooms/v2.md
View file

@ -49,7 +49,7 @@ completeness.
Events in rooms of this version have the following structure: Events in rooms of this version have the following structure:
{{% definition path="api/server-server/definitions/pdu" %}} {{% definition path="api/server-server/definitions/pdu_v1" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

29
content/rooms/v6.md
View file

@ -39,6 +39,13 @@ in [room version 5](/rooms/v5).
[See above](#redactions). [See above](#redactions).
### Event format
{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
the `depth` limit has been reduced in this room version.
{{% rver-fragment name="v6-event-format" %}}
### Authorization rules ### Authorization rules
{{% added-in v=6 %}} Rule 4, which related specifically to events {{% added-in v=6 %}} Rule 4, which related specifically to events
@ -88,14 +95,20 @@ The rules are as follows:
version, reject. version, reject.
4. If `content` has no `creator` property, reject. 4. If `content` has no `creator` property, reject.
5. Otherwise, allow. 5. Otherwise, allow.
2. Reject if event has `auth_events` that: 2. Considering the event's `auth_events`:
1. have duplicate entries for a given `type` and `state_key` pair 1. If there are duplicate entries for a given `type` and `state_key` pair,
2. have entries whose `type` and `state_key` don't match those reject.
2. If there are entries whose `type` and `state_key` don't match those
specified by the [auth events specified by the [auth events
selection](/server-server-api#auth-events-selection) selection](/server-server-api#auth-events-selection)
algorithm described in the server specification. algorithm described in the server specification, reject.
3. If event does not have a `m.room.create` in its `auth_events`, 3. If there are entries which were themselves rejected under the [checks
reject. performed on receipt of a
PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
4. If there is no `m.room.create` event among the entries, reject.
3. If the `content` of the `m.room.create` event in the room state has the
property `m.federate` set to `false`, and the `sender` domain of the event
does not match the `sender` domain of the create event, reject.
4. If type is `m.room.member`: 4. If type is `m.room.member`:
1. If there is no `state_key` property, or no `membership` property in 1. If there is no `state_key` property, or no `membership` property in
`content`, reject. `content`, reject.
@ -223,10 +236,6 @@ completeness.
{{% rver-fragment name="v4-event-ids" %}} {{% rver-fragment name="v4-event-ids" %}}
### Event format
{{% rver-fragment name="v4-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas
{{% rver-fragment name="v1-deprecated-formatting-off-spec" %}} {{% rver-fragment name="v1-deprecated-formatting-off-spec" %}}

20
content/rooms/v7.md
View file

@ -74,14 +74,20 @@ The rules are as follows:
version, reject. version, reject.
4. If `content` has no `creator` property, reject. 4. If `content` has no `creator` property, reject.
5. Otherwise, allow. 5. Otherwise, allow.
2. Reject if event has `auth_events` that: 2. Considering the event's `auth_events`:
1. have duplicate entries for a given `type` and `state_key` pair 1. If there are duplicate entries for a given `type` and `state_key` pair,
2. have entries whose `type` and `state_key` don't match those reject.
2. If there are entries whose `type` and `state_key` don't match those
specified by the [auth events specified by the [auth events
selection](/server-server-api#auth-events-selection) selection](/server-server-api#auth-events-selection)
algorithm described in the server specification. algorithm described in the server specification, reject.
3. If event does not have a `m.room.create` in its `auth_events`, 3. If there are entries which were themselves rejected under the [checks
reject. performed on receipt of a
PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
4. If there is no `m.room.create` event among the entries, reject.
3. If the `content` of the `m.room.create` event in the room state has the
property `m.federate` set to `false`, and the `sender` domain of the event
does not match the `sender` domain of the create event, reject.
4. If type is `m.room.member`: 4. If type is `m.room.member`:
1. If there is no `state_key` property, or no `membership` property in 1. If there is no `state_key` property, or no `membership` property in
`content`, reject. `content`, reject.
@ -219,7 +225,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

2
content/rooms/v8.md
View file

@ -109,7 +109,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

2
content/rooms/v9.md
View file

@ -74,7 +74,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

4
content/server-server-api.md
View file

@ -537,7 +537,7 @@ the following subset of the room state:
- If type is `m.room.member`: - If type is `m.room.member`:
- The target's current `m.room.member` event, if any. - The target's current `m.room.member` event, if any.
- If `membership` is `join` or `invite`, the current - If `membership` is `join`, `invite` or `knock`, the current
`m.room.join_rules` event, if any. `m.room.join_rules` event, if any.
- If membership is `invite` and `content` contains a - If membership is `invite` and `content` contains a
`third_party_invite` property, the current `third_party_invite` property, the current
@ -1337,7 +1337,7 @@ calculated as follows.
The *content hash* of an event covers the complete event including the The *content hash* of an event covers the complete event including the
*unredacted* contents. It is calculated as follows. *unredacted* contents. It is calculated as follows.
First, any existing `unsigned`, `signature`, and `hashes` members are First, any existing `unsigned`, `signatures`, and `hashes` properties are
removed. The resulting object is then encoded as [Canonical removed. The resulting object is then encoded as [Canonical
JSON](/appendices#canonical-json), and the JSON is hashed using JSON](/appendices#canonical-json), and the JSON is hashed using
SHA-256. SHA-256.

27
data/api/client-server/create_room.yaml
View file

@ -131,32 +131,7 @@ paths:
A list of objects representing third-party IDs to invite into A list of objects representing third-party IDs to invite into
the room. the room.
items: items:
type: object $ref: definitions/invite_3pid.yaml
title: Invite3pid
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
description: |-
The kind of address being passed in the address field, for example `email`
(see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third-party identifier.
required:
- id_server
- id_access_token
- medium
- address
room_version: room_version:
type: string type: string
description: |- description: |-

45
data/api/client-server/definitions/invite_3pid.yaml Normal file
View file

@ -0,0 +1,45 @@
# Copyright 2025 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Invite3pid
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
description: |-
The kind of address being passed in the address field, for example `email`
(see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third-party identifier.
required:
- id_server
- id_access_token
- medium
- address
example: {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"medium": "email",
"address": "cheeky@monkey.com"
}

122
data/api/client-server/key_backup.yaml
View file

@ -438,22 +438,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object $ref: "#/components/schemas/RoomKeysUpdateResponse"
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"403": "403":
description: |- description: |-
The version specified does not match the current backup version. The version specified does not match the current backup version.
@ -571,22 +556,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object $ref: "#/components/schemas/RoomKeysUpdateResponse"
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"404": "404":
description: The backup was not found. description: The backup was not found.
content: content:
@ -644,22 +614,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object $ref: "#/components/schemas/RoomKeysUpdateResponse"
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"403": "403":
description: |- description: |-
The version specified does not match the current backup version. The version specified does not match the current backup version.
@ -778,22 +733,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object $ref: "#/components/schemas/RoomKeysUpdateResponse"
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"404": "404":
description: The backup was not found. description: The backup was not found.
content: content:
@ -866,22 +806,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object $ref: "#/components/schemas/RoomKeysUpdateResponse"
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"403": "403":
description: |- description: |-
The version specified does not match the current backup version. The version specified does not match the current backup version.
@ -1007,22 +932,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object $ref: "#/components/schemas/RoomKeysUpdateResponse"
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"404": "404":
description: The backup was not found. description: The backup was not found.
content: content:
@ -1056,6 +966,26 @@ servers:
basePath: basePath:
default: /_matrix/client/v3 default: /_matrix/client/v3
components: components:
schemas:
RoomKeysUpdateResponse:
type: object
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)
for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
securitySchemes: securitySchemes:
accessTokenQuery: accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery $ref: definitions/security.yaml#/accessTokenQuery

2
data/api/client-server/old_sync.yaml
View file

@ -214,7 +214,7 @@ paths:
- public - public
description: |- description: |-
Whether this room is visible to the `/publicRooms` API Whether this room is visible to the `/publicRooms` API
or not." or not.
account_data: account_data:
type: array type: array
description: |- description: |-

97
data/api/client-server/report_content.yaml
View file

@ -45,7 +45,9 @@ paths:
properties: properties:
reason: reason:
type: string type: string
description: The reason the room is being reported. description: The reason the room is being reported. May be blank.
required:
- reason
required: true required: true
security: security:
- accessTokenQuery: [] - accessTokenQuery: []
@ -88,12 +90,11 @@ paths:
Reports an event as inappropriate to the server, which may then notify Reports an event as inappropriate to the server, which may then notify
the appropriate people. The caller must be joined to the room to report the appropriate people. The caller must be joined to the room to report
it. it.
It might be possible for clients to deduce whether an event exists by Furthermore, it might be possible for clients to deduce whether a reported
timing the response, as only a report for an event that does exist event exists by timing the response. This is because only a report for an
will require the homeserver to check whether a user is joined to existing event will require the homeserver to do further processing. To
the room. To combat this, homeserver implementations should add combat this, homeservers MAY add a random delay when generating a response.
a random delay when generating a response.
operationId: reportEvent operationId: reportEvent
parameters: parameters:
- in: path - in: path
@ -164,6 +165,88 @@ paths:
} }
tags: tags:
- Reporting content - Reporting content
"/users/{userId}/report":
post:
x-addedInMatrixVersion: "1.14"
summary: Report a user as inappropriate.
description: |-
Reports a user as inappropriate to the server, which may then notify
the appropriate people. How such information is delivered is left up to
implementations. The caller is not required to be joined to any rooms
that the reported user is joined to.
Clients may wish to [ignore](#ignoring-users) users after reporting them.
Clients could infer whether a reported user exists based on the 404 response.
Homeservers that wish to conceal this information MAY return 200 responses
regardless of the existence of the reported user.
Furthermore, it might be possible for clients to deduce whether a reported
user exists by timing the response. This is because only a report for an
existing user will require the homeserver to do further processing. To
combat this, homeservers MAY add a random delay when generating a response.
operationId: reportUser
parameters:
- in: path
name: userId
description: The user being reported.
required: true
example: "@someguy:example.com"
schema:
type: string
format: mx-user-id
pattern: "^@"
requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "this makes me sad"
}
properties:
reason:
type: string
description: The reason the room is being reported. May be blank.
required:
- reason
required: true
security:
- accessTokenQuery: []
- accessTokenBearer: []
responses:
"200":
description: |
The user has been reported successfully or the server chose
to not disclose whether the users exists.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"404":
description: |-
The user was not found on the homeserver.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The user was not found."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Reporting content
servers: servers:
- url: "{protocol}://{hostname}{basePath}" - url: "{protocol}://{hostname}{basePath}"
variables: variables:

2
data/api/client-server/room_initial_sync.yaml
View file

@ -96,7 +96,7 @@ paths:
- public - public
description: |- description: |-
Whether this room is visible to the `/publicRooms` API Whether this room is visible to the `/publicRooms` API
or not." or not.
account_data: account_data:
type: array type: array
description: The private data that this user has attached to this room. description: The private data that this user has attached to this room.

46
data/api/client-server/sync.yaml
View file

@ -441,17 +441,57 @@ paths:
"state": { "state": {
"events": [ "events": [
{ {
"$ref": "../../event-schemas/examples/m.room.member.yaml" "content": {
"avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
"displayname": "Example user",
"membership": "join"
},
"event_id": "$143273976499sgjks:example.org",
"origin_server_ts": 1432735824653,
"sender": "@example:example.org",
"state_key": "@example:example.org",
"type": "m.room.member",
"unsigned": {
"age": 45603,
"membership": "join"
}
} }
] ]
}, },
"timeline": { "timeline": {
"events": [ "events": [
{ {
"$ref": "../../event-schemas/examples/m.room.member.yaml" "content": {
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid",
"membership": "join",
"reason": "Looking for support"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"sender": "@alice:example.org",
"state_key": "@alice:example.org",
"type": "m.room.member",
"unsigned": {
"age": 1234,
"membership": "join"
}
}, },
{ {
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" "content": {
"body": "This is an example text message",
"format": "org.matrix.custom.html",
"formatted_body": "<b>This is an example text message</b>",
"msgtype": "m.text"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"sender": "@example:example.org",
"type": "m.room.message",
"unsigned": {
"age": 1234,
"membership": "join"
}
} }
], ],
"limited": true, "limited": true,

32
data/api/client-server/third_party_membership.yaml
View file

@ -76,37 +76,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object $ref: definitions/invite_3pid.yaml
example: {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"medium": "email",
"address": "cheeky@monkey.com"
}
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for
third-party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
description: |-
The kind of address being passed in the address field, for example
`email` (see [the list of recognised values](/appendices/#3pid-types)).
address:
type: string
description: The invitee's third-party identifier.
required:
- id_server
- id_access_token
- medium
- address
required: true required: true
responses: responses:
"200": "200":

45
data/api/server-server/definitions/components/auth_events_prev_events_v4.yaml Normal file
View file

@ -0,0 +1,45 @@
# Copyright 2025 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
description: |-
The auth_events and prev_events fields of PDUs for room version 4
and beyond.
properties:
auth_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the authorization events that would
allow this event to be in the room.
Must contain less than or equal to 10 events. Note that if the relevant
auth event selection rules are used, this restriction should never be
encountered.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
prev_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the most recent events in the room
that the homeserver was aware of when it made this event.
Must contain less than or equal to 20 events.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
required:
- auth_events
- prev_events

0
data/api/server-server/definitions/event_hash.yaml → data/api/server-server/definitions/components/event_hash.yaml
View file

67
data/api/server-server/definitions/unsigned_pdu_base.yaml → data/api/server-server/definitions/components/pdu_base.yaml
View file

@ -12,10 +12,7 @@
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
type: object type: object
title: Unsigned Persistent Data Unit description: Common fields for all PDU versions
description: An unsigned persistent data unit (event)
example:
$ref: "../examples/unsigned_pdu_base.json"
properties: properties:
room_id: room_id:
type: string type: string
@ -44,49 +41,22 @@ properties:
type: object type: object
description: The content of the event. description: The content of the event.
example: {"key": "value"} example: {"key": "value"}
prev_events: hashes:
type: array $ref: "event_hash.yaml"
signatures:
type: object
description: |- description: |-
Event IDs and reference hashes for the most recent events in the room Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
that the homeserver was aware of when it made this event. example: {
"example.com": {
Must contain less than or equal to 20 events. "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
items: }
type: array }
maxItems: 2 additionalProperties:
minItems: 2 type: object
items: title: Server Signatures
anyOf: additionalProperties:
- type: string type: string
title: Event ID
example: "$abc123:matrix.org"
- $ref: "event_hash.yaml"
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12
auth_events:
type: array
description: |-
Event IDs and reference hashes for the authorization events that would
allow this event to be in the room.
Must contain less than or equal to 10 events. Note that if the relevant
auth event selection rules are used, this restriction should never be
encountered.
items:
type: array
maxItems: 2
minItems: 2
items:
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- $ref: "event_hash.yaml"
unsigned: unsigned:
type: object type: object
title: UnsignedData title: UnsignedData
@ -99,12 +69,11 @@ properties:
description: The number of milliseconds that have passed since this message was sent. description: The number of milliseconds that have passed since this message was sent.
example: 4612 example: 4612
required: required:
- event_id
- room_id - room_id
- sender - sender
- origin_server_ts - origin_server_ts
- type - type
- content - content
- prev_events
- depth - depth
- auth_events - hashes
- signatures

77
data/api/server-server/definitions/pdu_v1.yaml Normal file
View file

@ -0,0 +1,77 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Persistent Data Unit
description: A persistent data unit (event) for room versions 1 and 2.
example:
$ref: "../examples/pdu_v1.json"
allOf:
- $ref: "components/pdu_base.yaml"
- type: object
properties:
event_id:
type: string
description: The event ID for the PDU.
example: "$a4ecee13e2accdadf56c1025:example.com"
redacts:
type: string
description: For redaction events, the ID of the event being redacted.
example: "$def456:matrix.org"
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12
auth_events:
type: array
description: |-
Event IDs and reference hashes for the authorization events that would
allow this event to be in the room.
Must contain less than or equal to 10 events. Note that if the relevant
auth event selection rules are used, this restriction should never be
encountered.
items:
type: array
maxItems: 2
minItems: 2
items:
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- $ref: "components/event_hash.yaml"
prev_events:
type: array
description: |-
Event IDs and reference hashes for the most recent events in the room
that the homeserver was aware of when it made this event.
Must contain less than or equal to 20 events.
items:
type: array
maxItems: 2
minItems: 2
items:
anyOf:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- $ref: "components/event_hash.yaml"
required:
- event_id
- auth_events
- prev_events

57
data/api/server-server/definitions/pdu_v11.yaml
View file

@ -17,53 +17,16 @@ description: A persistent data unit (event) for room version 11 and beyond.
example: example:
$ref: "../examples/pdu_v11.json" $ref: "../examples/pdu_v11.json"
allOf: allOf:
# v11 is the v4 event, but without redacts. Copy the auth_events/prev_events # v11 is the v6 event, but without redacts.
# from pdu_v4.yaml and hashes and signatures from pdu_v3.yaml. - $ref: "components/pdu_base.yaml"
- $ref: "unsigned_pdu_base.yaml" - $ref: "components/auth_events_prev_events_v4.yaml"
- type: object - type: object
properties: properties:
auth_events: # v6 enforces Canonical JSON and therefore needs a depth limit change
type: array depth:
items: type: integer
type: string
description: Event ID.
description: |- description: |-
Event IDs for the authorization events that would The maximum depth of the `prev_events`, plus one. Must be less than the
allow this event to be in the room. maximum value for an integer (2^53 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
Must contain less than or equal to 10 events. Note that if the relevant example: 12
auth event selection rules are used, this restriction should never be
encountered.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
prev_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the most recent events in the room
that the homeserver was aware of when it made this event.
Must contain less than or equal to 20 events.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
hashes:
$ref: "event_hash.yaml"
signatures:
type: object
description: |-
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
example: {
"example.com": {
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
}
}
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string
required:
- auth_events
- prev_events
- hashes
- signatures

29
data/api/server-server/definitions/pdu_v3.yaml
View file

@ -13,17 +13,24 @@
# limitations under the License. # limitations under the License.
type: object type: object
title: Persistent Data Unit title: Persistent Data Unit
description: A persistent data unit (event) for room version 3 and beyond. description: A persistent data unit (event) for room version 3.
example: example:
$ref: "../examples/pdu_v3.json" $ref: "../examples/pdu_v3.json"
allOf: allOf:
- $ref: "unsigned_pdu_base.yaml" - $ref: "components/pdu_base.yaml"
- type: object - type: object
properties: properties:
redacts: redacts:
type: string type: string
description: For redaction events, the ID of the event being redacted. description: For redaction events, the ID of the event being redacted.
example: "$def/456+oldevent" example: "$def/456+oldevent"
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12
auth_events: auth_events:
type: array type: array
items: items:
@ -48,24 +55,6 @@ allOf:
Must contain less than or equal to 20 events. Must contain less than or equal to 20 events.
example: ["$base64EncodedHash", "$AnotherEvent"] example: ["$base64EncodedHash", "$AnotherEvent"]
hashes:
$ref: "event_hash.yaml"
signatures:
type: object
description: |-
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
example: {
"example.com": {
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
}
}
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string
required: required:
- auth_events - auth_events
- prev_events - prev_events
- hashes
- signatures

38
data/api/server-server/definitions/pdu_v4.yaml
View file

@ -13,41 +13,23 @@
# limitations under the License. # limitations under the License.
type: object type: object
title: Persistent Data Unit title: Persistent Data Unit
description: A persistent data unit (event) for room version 4 and beyond. description: |-
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
example: example:
$ref: "../examples/pdu_v4.json" $ref: "../examples/pdu_v4.json"
allOf: allOf:
- $ref: "pdu_v3.yaml" - $ref: "components/pdu_base.yaml"
- $ref: "components/auth_events_prev_events_v4.yaml"
- type: object - type: object
properties: properties:
redacts: redacts:
type: string type: string
description: For redaction events, the ID of the event being redacted. description: For redaction events, the ID of the event being redacted.
example: "$def_456-oldevent" example: "$def_456-oldevent"
auth_events: depth:
type: array type: integer
items:
type: string
description: Event ID.
description: |- description: |-
Event IDs for the authorization events that would The maximum depth of the `prev_events`, plus one. Must be less than the
allow this event to be in the room. maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
Must contain less than or equal to 10 events. Note that if the relevant example: 12
auth event selection rules are used, this restriction should never be
encountered.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
prev_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the most recent events in the room
that the homeserver was aware of when it made this event.
Must contain less than or equal to 20 events.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
required:
- auth_events
- prev_events

37
data/api/server-server/definitions/pdu.yaml → data/api/server-server/definitions/pdu_v6.yaml
View file

@ -1,4 +1,4 @@
# Copyright 2018 New Vector Ltd # Copyright 2025 The Matrix.org Foundation C.I.C.
# #
# Licensed under the Apache License, Version 2.0 (the "License"); # Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License. # you may not use this file except in compliance with the License.
@ -13,33 +13,24 @@
# limitations under the License. # limitations under the License.
type: object type: object
title: Persistent Data Unit title: Persistent Data Unit
description: A persistent data unit (event) for room versions 1 and 2. description: |-
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
example: example:
$ref: "../examples/pdu.json" $ref: "../examples/pdu_v4.json"
allOf: allOf:
- $ref: "unsigned_pdu.yaml" - $ref: "components/pdu_base.yaml"
- $ref: "components/auth_events_prev_events_v4.yaml"
- type: object - type: object
properties: properties:
redacts: redacts:
type: string type: string
description: For redaction events, the ID of the event being redacted. description: For redaction events, the ID of the event being redacted.
example: "$def456:matrix.org" example: "$def_456-oldevent"
hashes: # v6 enforces Canonical JSON and therefore needs a depth limit change
$ref: "event_hash.yaml" depth:
signatures: type: integer
type: object
description: |- description: |-
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). The maximum depth of the `prev_events`, plus one. Must be less than the
example: { maximum value for an integer (2^53 - 1). If the room's depth is already at
"example.com": { the limit, the depth must be set to the limit.
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent" example: 12
}
}
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string
required:
- hashes
- signatures

28
data/api/server-server/definitions/unsigned_pdu.yaml
View file

@ -1,28 +0,0 @@
# Copyright 2018-2019 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Unsigned Persistent Data Unit
description: An unsigned persistent data unit (event)
example:
$ref: "../examples/unsigned_pdu.json"
allOf:
- $ref: "unsigned_pdu_base.yaml"
- type: object
properties:
event_id:
type: string
description: The event ID for the PDU.
example: "$a4ecee13e2accdadf56c1025:example.com"
required:
- event_id

10
data/api/server-server/examples/components/auth_events_prev_events_v4.json Normal file
View file

@ -0,0 +1,10 @@
{
"auth_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
],
"prev_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
]
}

21
data/api/server-server/examples/components/pdu_base.json Normal file
View file

@ -0,0 +1,21 @@
{
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
"sender": "@alice:example.com",
"origin_server_ts": 1404838188000,
"depth": 12,
"type": "m.room.message",
"content": {
"key": "value"
},
"hashes": {
"sha256": "thishashcoversallfieldsincasethisisredacted"
},
"signatures": {
"example.com": {
"ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
},
"unsigned": {
"age": 4612
}
}

11
data/api/server-server/examples/pdu.json
View file

@ -1,11 +0,0 @@
{
"$ref": "unsigned_pdu.json",
"hashes": {
"sha256": "thishashcoversallfieldsincasethisisredacted"
},
"signatures": {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
}
}

17
data/api/server-server/examples/unsigned_pdu_base.json → data/api/server-server/examples/pdu_v1.json
View file

@ -1,25 +1,16 @@
{ {
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org", "$ref": "components/pdu_base.json",
"sender": "@alice:example.com", "event_id": "$a4ecee13e2accdadf56c1025:example.com",
"origin_server_ts": 1404838188000,
"depth": 12,
"auth_events": [ "auth_events": [
[ [
"$af232176:example.org", "$af232176:example.org",
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"} {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
] ]
], ],
"type": "m.room.message",
"prev_events": [ "prev_events": [
[ [
"$af232176:example.org", "$af232176:example.org",
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"} {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
] ]
], ]
"content": { }
"key": "value"
},
"unsigned": {
"age": 4612
}
}

19
data/api/server-server/examples/pdu_v11.json
View file

@ -1,19 +1,6 @@
{ {
"$ref": "unsigned_pdu_base.json", "allOf": [
"hashes": { { "$ref": "components/pdu_base.json" },
"sha256": "thishashcoversallfieldsincasethisisredacted" { "$ref": "components/auth_events_prev_events_v4.json" }
},
"signatures": {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
},
"auth_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
],
"prev_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
] ]
} }

10
data/api/server-server/examples/pdu_v3.json
View file

@ -1,13 +1,5 @@
{ {
"$ref": "unsigned_pdu_base.json", "$ref": "components/pdu_base.json",
"hashes": {
"sha256": "thishashcoversallfieldsincasethisisredacted"
},
"signatures": {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
},
"auth_events": [ "auth_events": [
"$base64encodedeventid", "$base64encodedeventid",
"$adifferenteventid" "$adifferenteventid"

15
data/api/server-server/examples/pdu_v4.json
View file

@ -1,12 +1,7 @@
{ {
"$ref": "pdu_v3.json", "allOf": [
"auth_events": [ { "$ref": "components/pdu_base.json" },
"$urlsafe_base64_encoded_eventid", { "$ref": "components/auth_events_prev_events_v4.json" },
"$a-different-event-id" { "redacts": "$some-old_event" }
], ]
"prev_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
],
"redacts": "$some-old_event"
} }

5
data/api/server-server/examples/pdu_v4_join_membership.json
View file

@ -1,8 +1,5 @@
{ {
"$ref": "unsigned_pdu_base.json", "$ref": "components/pdu_base.json",
"hashes": {
"sha256": "thishashcoversallfieldsincasethisisredacted"
},
"signatures": { "signatures": {
"example.com": { "example.com": {
"ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"

4
data/api/server-server/examples/unsigned_pdu.json
View file

@ -1,4 +0,0 @@
{
"$ref": "unsigned_pdu_base.json",
"event_id": "$a4ecee13e2accdadf56c1025:example.com"
}

16
data/api/server-server/invites-v1.yaml
View file

@ -75,22 +75,6 @@ paths:
example: example:
$ref: ../../event-schemas/examples/invite_room_state.json $ref: ../../event-schemas/examples/invite_room_state.json
type: object type: object
example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
}
required: true required: true
responses: responses:
"200": "200":

19
data/api/server-server/invites-v2.yaml
View file

@ -78,25 +78,6 @@ paths:
required: required:
- room_version - room_version
- event - event
example: {
"room_version": "2",
"event": {
"room_id": "!somewhere:example.org",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
}
}
required: true required: true
responses: responses:
"200": "200":

1
data/api/server-server/joins-v2.yaml
View file

@ -140,7 +140,6 @@ paths:
- type - type
- content - content
example: { example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member", "type": "m.room.member",
"state_key": "@someone:example.org", "state_key": "@someone:example.org",
"origin": "example.org", "origin": "example.org",

1
data/api/server-server/knocks.yaml
View file

@ -270,7 +270,6 @@ paths:
- type - type
- content - content
example: { example: {
"room_id": "!somewhere:example.org",
"type": "m.room.member", "type": "m.room.member",
"state_key": "@someone:example.org", "state_key": "@someone:example.org",
"origin": "example.org", "origin": "example.org",

1
data/event-schemas/examples/m.room.member.yaml
View file

@ -1,6 +1,7 @@
{ {
"$ref": "core/state_event.json", "$ref": "core/state_event.json",
"state_key": "@alice:example.org", "state_key": "@alice:example.org",
"sender": "@alice:example.org",
"type": "m.room.member", "type": "m.room.member",
"content": { "content": {
"membership": "join", "membership": "join",

9
data/event-schemas/schema/m.room.topic.yaml
View file

@ -1,7 +1,14 @@
--- ---
allOf: allOf:
- $ref: core-event-schema/state_event.yaml - $ref: core-event-schema/state_event.yaml
description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.' description: |-
A topic is a short message detailing what is currently being discussed in the room.
It can also be used as a way to display extra information about the room, which may not
be suitable for the room name.
The room topic can also be set when creating a room using `/createRoom` with the `topic` key.'
If the `topic` property is absent, null, or empty then the topic is unset. In other words,
an empty `topic` property effectively resets the room to having no topic.
properties: properties:
content: content:
properties: properties:

4
data/event-schemas/schema/m.room_key.withheld.yaml
View file

@ -48,8 +48,8 @@ properties:
session_id: session_id:
type: string type: string
description: |- description: |-
Required of `code` is not `m.no_olm`. The session ID of the key Required if `code` is not `m.no_olm`. The session ID of the key
that this event is aboutis for. that this event is about.
sender_key: sender_key:
type: string type: string
description: |- description: |-

12
layouts/docs/changelog.html
View file

@ -31,9 +31,17 @@
<h1>{{ .Title }}</h1> <h1>{{ .Title }}</h1>
<table class="release-info"> <table class="release-info">
{{ if ne $version "unstable" -}} {{ $rev := $version }}
{{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $version -}} {{ if eq $version "unstable" -}}
{{- /*
Extract the git SHA from the frontmatter of the changelog, where
it was stashed by `generate-changelog.sh`.
*/ -}}
{{ $rev = .Params.commit -}}
{{ end -}}
{{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $rev -}}
<tr><th>Git commit</th><td><a href="{{ $commitLink }}">{{ $commitLink }}</a></td> <tr><th>Git commit</th><td><a href="{{ $commitLink }}">{{ $commitLink }}</a></td>
{{ if ne $version "unstable" }}
<tr><th>Release date</th><td>{{ .Date | time.Format ":date_long" }}</td> <tr><th>Release date</th><td>{{ .Date | time.Format ":date_long" }}</td>
{{ end -}} {{ end -}}
{{ $checklist := .OutputFormats.Get "checklist" -}} {{ $checklist := .OutputFormats.Get "checklist" -}}

8
layouts/partials/events/example.html
View file

@ -13,10 +13,4 @@
{{ $path := delimit (slice "event-schemas/examples" .name) "/" }} {{ $path := delimit (slice "event-schemas/examples" .name) "/" }}
{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .schema "path" $path) }} {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .schema "path" $path) }}
{{ $example_json := jsonify (dict "indent" " ") $example_content }} {{ partial "render-example" (dict "example" $example_content) }}
{{ $example_json = replace $example_json "\\u003c" "<" }}
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
```json
{{ $example_json }}
```

8
layouts/partials/json-schema/resolve-allof.html
View file

@ -24,6 +24,14 @@
{{ range $original }} {{ range $original }}
{{ $resolved := partial "json-schema/resolve-allof" . }} {{ $resolved := partial "json-schema/resolve-allof" . }}
{{ if reflect.IsSlice $resolved }}
{{/*
If $resolved is a slice, `append` will add the items of $resolved to
$ret, but we want to add $resolved itself to $ret, so we always wrap
it into another slice.
*/}}
{{ $resolved = slice $resolved }}
{{ end }}
{{ $ret = $ret | append $resolved }} {{ $ret = $ret | append $resolved }}
{{ end }} {{ end }}
{{ else if reflect.IsMap $original }} {{ else if reflect.IsMap $original }}

46
layouts/partials/json-schema/resolve-example.html
View file

@ -1,46 +0,0 @@
{{/*
For complex objects, example content is sometimes attached to the
object's individual properties (and subproperties...), so to get
a complete example for the whole object we need to iterate through
its properties (and subproperties...) and assemble them.
That's what this template does.
*/}}
{{ $this_object := . }}
{{ $example := $this_object.example }}
{{ if not $example }}
{{ if eq $this_object.type "object" }}
{{ $example = dict }}
{{ range $key, $property := $this_object.properties}}
{{ $this_property_example := partial "json-schema/resolve-example" $property }}
{{ if $this_property_example }}
{{ $example = merge (dict $key $this_property_example) $example }}
{{ end }}
{{ end }}
{{ else if eq $this_object.type "array" }}
{{/* the "items" within an array can either be an object (where we have a
list of items which match the schema), or a list (for tuple
validation, where each item has a different schema).
TODO: support tuple validation here.
*/}}
{{ if reflect.IsMap $this_object.items }}
{{ $items_example := partial "json-schema/resolve-example" $this_object.items }}
{{ if $items_example }}
{{ $example = slice $items_example }}
{{ end }}
{{ end }}
{{ end }}
{{ end }}
{{ return $example }}

71
layouts/partials/json-schema/resolve-examples.html Normal file
View file

@ -0,0 +1,71 @@
{{/*
Find examples in the given JSON schema.
Tries to find examples in the `examples` and `example` keys of the schema
first.
If it doesn't succeed, iterates through the properties and subproperties to
collect their examples, to merge them into a complete example for the whole
object.
Parameter: the JSON schema to extract the examples from.
*/}}
{{ $this_object := . }}
{{ $examples := slice }}
{{ if $this_object.examples }}
{{/* This is an array of examples, we can just use it */}}
{{ $examples = $this_object.examples }}
{{ else if $this_object.example }}
{{ $examples = slice $this_object.example }}
{{ else }}
{{/* Resolve the nested examples */}}
{{ if eq $this_object.type "object" }}
{{ $example := dict }}
{{ range $key, $property := $this_object.properties}}
{{ $this_property_examples := partial "json-schema/resolve-examples" $property }}
{{/*
It would be too complex to handle several nested examples,
just use the first one.
*/}}
{{ with index $this_property_examples 0 }}
{{ $example = merge (dict $key .) $example }}
{{ end }}
{{ end }}
{{/*
Add the assembled example to the list if either (a) the example is
non-empty, or (b) the object itself is meant to be empty (so an
empty example is correct).
*/}}
{{ if (or $example (not $this_object.properties)) }}
{{ $examples = slice $example }}
{{ end }}
{{ else if eq $this_object.type "array" }}
{{/* the "items" within an array can either be an object (where we have a
list of items which match the schema), or a list (for tuple
validation, where each item has a different schema).
TODO: support tuple validation here.
*/}}
{{ if reflect.IsMap $this_object.items }}
{{ $items_examples := partial "json-schema/resolve-examples" $this_object.items }}
{{/*
It would be too complex to handle several nested examples,
just use the first one.
*/}}
{{ with index $items_examples 0 }}
{{ $examples = slice (slice .) }}
{{ end }}
{{ end }}
{{ end }}
{{ end }}
{{ return $examples }}

8
layouts/partials/json-schema/resolve-refs.html
View file

@ -69,6 +69,14 @@
{{ range $schema }} {{ range $schema }}
{{ $resolved := partial "json-schema/resolve-refs" (dict "schema" . "path" $path) }} {{ $resolved := partial "json-schema/resolve-refs" (dict "schema" . "path" $path) }}
{{ if reflect.IsSlice $resolved }}
{{/*
If $resolved is a slice, `append` will add the items of $resolved to
$result_slice, but we want to add $resolved itself to $result_slice,
so we wrap it into another slice.
*/}}
{{ $resolved = slice $resolved }}
{{ end }}
{{ $result_slice = $result_slice | append $resolved }} {{ $result_slice = $result_slice | append $resolved }}
{{ end }} {{ end }}

104
layouts/partials/openapi/render-media-type-objects.html Normal file
View file

@ -0,0 +1,104 @@
{{/*
Render a map of [Media Type Objects](https://spec.openapis.org/oas/v3.1.1#media-type-object).
This map can be found as the `content` field of requests and responses.
Parameters:
* `content`: A map of MIME type to Media Type Object
* `kind`: the kind of object that is rendered, either `request` or `response`.
* `anchor_base`: a prefix to add to the HTML anchors generated for each object
This template renders:
* Object tables if the map contains an `application/json` MIME type, or a
table with the MIME types and the corresponding description of the object.
* The examples of the Media Type Objects.
*/}}
{{/*
Request and response bodies can have several content types. If there is a
JSON type, we display that; otherwise we just show the content types and
descriptions.
*/}}
{{ $json_body := index .content "application/json" }}
{{ if $json_body }}
{{/*
Display the JSON schemas
*/}}
{{ $schema := $json_body.schema }}
{{/*
All this is to work out how to express the content of the response
in the case where it is an array.
*/}}
{{ if eq $schema.type "array" }}
{{ $type_of := "" }}
{{ if $schema.items.anyOf }}
{{ $types := slice }}
{{ range $schema.items.anyOf }}
{{ if .title }}
{{ $types = $types | append .title}}
{{ else }}
{{ $types = $types | append .type }}
{{ end }}
{{ end }}
{{ $type_of = delimit $types ", "}}
{{ else }}
{{ $type_of = $schema.items.title }}
{{ end }}
<p>Array of <code>{{ $type_of }}</code>.</p>
{{ end }}
{{/*
Render object tables for any objects referenced in the request/response.
This will be a no-op for request/response body types which aren't
objects or arrays.
*/}}
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" .anchor_base) }}
{{ range $additional_types }}
{{ partial "openapi/render-object-table" . }}
{{ end }}
{{ else }}
{{/*
Show the content types and description.
*/}}
{{ partial "openapi/render-content-type" (dict "content_types" .content) }}
{{ end }}
{{/*
Show all the examples.
*/}}
{{ if eq .kind "request" }}
<h3>Request body example</h3>
{{ end }}
{{ range $mime, $body := .content }}
{{ $examples := slice }}
{{/*
Find the examples to display, with the following priority:
1. The `examples` field
2. The `example` field
3. The examples in the `schema` field
*/}}
{{ if $body.examples }}
{{/* This is a map of string to Example Object */}}
{{ range $key, $example := $body.examples }}
{{/* The example is in the `value` field of the object */}}
{{ $examples = $examples | append (slice $example.value) }}
{{ end }}
{{ else if $body.example }}
{{ $examples = slice $body.example }}
{{ else if $body.schema }}
{{ $examples = partial "json-schema/resolve-examples" $body.schema }}
{{ end }}
{{ range $examples }}
{{ partial "render-example" (dict "example" . "mime" $mime) }}
{{ end }}
{{ end }}

59
layouts/partials/openapi/render-request.html
View file

@ -33,65 +33,8 @@
{{ if $request_body }} {{ if $request_body }}
<h3>Request body</h3> <h3>Request body</h3>
{{/*
A request can have several content types.
*/}}
{{ $json_body := index $request_body.content "application/json" }}
{{ if $json_body }}
{{/*
Display the JSON schemas
*/}}
{{ $schema := $json_body.schema }}
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }} {{ partial "openapi/render-media-type-objects" (dict "content" $request_body.content "kind" "request" "anchor_base" $anchor) }}
{{ range $additional_types }}
{{ partial "openapi/render-object-table" . }}
{{ end }}
{{ else }}
{{/*
Show the content types and description.
*/}}
{{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }}
{{ end }}
<h3>Request body example</h3>
{{/*
Show all the examples.
*/}}
{{ range $mime, $body := $request_body.content }}
{{ $example := dict }}
{{ if $body.schema }}
{{ $example = partial "json-schema/resolve-example" $body.schema }}
{{ end }}
{{ if and (eq ($example | len) 0) $body.example }}
{{/*
If no example was generated from the schema, fallback to the
main example.
*/}}
{{ $example = $body.example }}
{{ end }}
{{ if eq $mime "application/json" }}
{{ $example_json := jsonify (dict "indent" " ") $example }}
{{ $example_json = replace $example_json "\\u003c" "<" }}
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
```json
{{ $example_json }}
```
{{ else }}
{{ $example = $example | safeHTML }}
{{/*
We need to set a language for the code otherwise the styling
is different than other examples.
*/}}
```json
{{ $example }}
```
{{ end }}
{{ end }}
{{ end }} {{ end }}
{{ else }} {{ else }}

68
layouts/partials/openapi/render-responses.html
View file

@ -59,72 +59,6 @@
{{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }} {{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }}
{{ end }} {{ end }}
{{/* {{ partial "openapi/render-media-type-objects" (dict "content" $response.content "kind" "response" "anchor_base" $anchor) }}
A response can have several content types.
*/}}
{{ $json_body := index $response.content "application/json" }}
{{ if $json_body }}
{{/*
Display the JSON schemas
*/}}
{{ $schema := $json_body.schema }}
{{/*
All this is to work out how to express the content of the response
in the case where it is an array.
*/}}
{{ if eq $schema.type "array" }}
{{ $type_of := "" }}
{{ if $schema.items.anyOf }}
{{ $types := slice }}
{{ range $schema.items.anyOf }}
{{ if .title }}
{{ $types = $types | append .title}}
{{ else }}
{{ $types = $types | append .type }}
{{ end }}
{{ end }}
{{ $type_of = delimit $types ", "}}
{{ else }}
{{ $type_of = $schema.items.title }}
{{ end }}
<p>Array of <code>{{ $type_of }}</code>.</p>
{{ end }}
{{/*
render object tables for any objects referenced in the
response. (This will be a no-op for response types which aren't
objects or arrays.)
*/}}
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
{{ range $additional_types }}
{{ partial "openapi/render-object-table" . }}
{{ end }}
{{/*
render an example. currently this is only supported for arrays and objects.
*/}}
{{ if or (eq $schema.type "object") (eq $schema.type "array") }}
{{ $example := partial "json-schema/resolve-example" $schema }}
{{ if $json_body.examples }}
{{ $example = $json_body.examples.response.value }}
{{ end }}
{{ $example_json := jsonify (dict "indent" " ") $example }}
{{ $example_json = replace $example_json "\\u003c" "<" }}
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
```json
{{ $example_json }}
```
{{ end }}
{{ else }}
{{/*
Show the content types and description.
*/}}
{{ partial "openapi/render-content-type" (dict "content_types" $response.content) }}
{{ end }}
{{ end }} {{ end }}
{{ end }} {{ end }}

40
layouts/partials/render-example.html Normal file
View file

@ -0,0 +1,40 @@
{{/*
Renders an example to be included in HTML, with support for pretty-printing
JSON.
Parameters:
* `example`: the example
* `mime`: the mime type of the example. Used to pretty-print JSON and for
syntax highlighting. If it is not provided, it is assumed to be
`application/json`.
*/}}
{{ $example := .example }}
{{/*
We need to convert the mime type to a recognized language.
For simplicity we only support JSON, which is also the default. Other mime
types are not highlighted.
*/}}
{{ $language := "json" }}
{{ if (and .mime (ne .mime "application/json")) }}
{{/*
`no-highlight` treats the value as plain text, but still styles the code
block like the ones with proper syntax highlighting.
*/}}
{{ $language = "no-highlight" }}
{{ end }}
{{ if eq $language "json" }}
{{ $example = jsonify (dict "indent" " ") $example }}
{{ $example = replace $example "\\u003c" "<" }}
{{ $example = replace $example "\\u003e" ">" }}
{{ end }}
```{{ $language }}
{{ $example | safeHTML }}
```

11
layouts/shortcodes/definition.html
View file

@ -58,13 +58,14 @@
{{ partial "openapi/render-object-table" . }} {{ partial "openapi/render-object-table" . }}
{{end}} {{end}}
{{ $examples := partial "json-schema/resolve-examples" $definition }}
{{ if $examples }}
<h2>Examples</h2> <h2>Examples</h2>
{{ $example := partial "json-schema/resolve-example" $definition }} {{ range $examples }}
{{ partial "render-example" (dict "example" .) }}
```json {{ end }}
{{ jsonify (dict "indent" " ") $example }} {{ end }}
```
</details> </details>

12
scripts/generate-changelog.sh
View file

@ -44,8 +44,18 @@ outputs:
- html - html
- checklist - checklist
date: $(date -Idate) date: $(date -Idate)
---
EOF EOF
# Add the commit hash for the unstable versions. It is used to generate a
# link to the commit on the repository.
if [ "$VERSION" == "vUNSTABLE" ]; then
echo "params:"
echo " commit: $(git rev-parse --short HEAD)"
fi
# Close the frontmatter.
echo "---"
# Remove trailing whitespace (such as our intentionally blank RST headings) # Remove trailing whitespace (such as our intentionally blank RST headings)
sed -e "s/[ ]*$//" rendered.md sed -e "s/[ ]*$//" rendered.md
} > ../content/changelog/$FILENAME } > ../content/changelog/$FILENAME

1
static/.well-known/funding-manifest-urls Normal file
View file

@ -0,0 +1 @@
https://matrix.org/funding.json