wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Change RST code formatting markup to Markdown

Browse source
This commit is contained in:
Will 2021-01-27 12:14:31 -08:00 • committed by Richard van der Hoff
parent c7cf90abfa
commit 27f8867aa0
158 changed files with 931 additions and 931 deletions
Download patch file Download diff file Expand all files Collapse all files

6
data/event-schemas/moderation_policy_rule.yaml
View file

@ -14,14 +14,14 @@
properties:
entity:
description: |-
The entity affected by this rule. Glob characters ``*`` and ``?`` can be used
The entity affected by this rule. Glob characters `*` and `?` can be used
to match zero or more and one or more characters respectively.
type: string
recommendation:
description: The suggested action to take. Currently only ``m.ban`` is specified.
description: The suggested action to take. Currently only `m.ban` is specified.
type: string
reason:
description: The human-readable description for the ``recommendation``.
description: The human-readable description for the `recommendation`.
type: string
type: object
required:

4
data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml
View file

@ -12,7 +12,7 @@ properties:
differ from the intrinsic dimensions of the image file.
type: integer
mimetype:
description: The mimetype of the image, e.g. ``image/jpeg``.
description: The mimetype of the image, e.g. `image/jpeg`.
type: string
size:
description: Size of the image in bytes.
@ -31,6 +31,6 @@ properties:
thumbnail_info:
allOf:
- $ref: thumbnail_info.yaml
description: Metadata about the image referred to in ``thumbnail_url``.
description: Metadata about the image referred to in `thumbnail_url`.
title: ImageInfo
type: object

2
data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml
View file

@ -12,7 +12,7 @@ properties:
differ from the intrinsic dimensions of the image file.
type: integer
mimetype:
description: The mimetype of the image, e.g. ``image/jpeg``.
description: The mimetype of the image, e.g. `image/jpeg`.
type: string
size:
description: Size of the image in bytes.

2
data/event-schemas/schema/core-event-schema/room_event.yaml
View file

@ -5,7 +5,7 @@ properties:
room_id:
description: |-
The ID of the room associated with this event. Will not be present on events
that arrive through ``/sync``, despite being required everywhere else.
that arrive through `/sync`, despite being required everywhere else.
type: string
required:
- room_id

4
data/event-schemas/schema/core-event-schema/sync_state_event.yaml
View file

@ -20,7 +20,7 @@ description: In addition to the Room Event fields, State Events have the followi
additional fields.
properties:
prev_content:
description: Optional. The previous ``content`` for this event. If there is no
description: Optional. The previous `content` for this event. If there is no
previous content, this key will be missing.
title: EventContent
type: object
@ -29,7 +29,7 @@ properties:
of room state. This value is often a zero-length string. The presence of this
key makes this event a State Event.
State keys starting with an ``@`` are reserved for referencing user IDs, such
State keys starting with an `@` are reserved for referencing user IDs, such
as room members. With the exception of a few events, state events set with a
given user's ID as the state key MUST only be set by that user.
type: string

2
data/event-schemas/schema/core-event-schema/unsigned_prop.yaml
View file

@ -29,6 +29,6 @@ properties:
transaction_id:
description: |
The client-supplied transaction ID, for example, provided via
``PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}``,
`PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}`,
if the client being given the event is the same one which sent it.
type: string

2
data/event-schemas/schema/m.call.hangup.yaml
View file

@ -18,7 +18,7 @@
},
"reason": {
"type": "string",
"description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be ``ice_failed`` for when ICE negotiation fails or ``invite_timeout`` for when the other party did not answer in time.",
"description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or `invite_timeout` for when the other party did not answer in time.",
"enum": [
"ice_failed",
"invite_timeout"

2
data/event-schemas/schema/m.direct.yaml
View file

@ -3,7 +3,7 @@ allOf:
- $ref: core-event-schema/event.yaml
description: |-
A map of which rooms are considered 'direct' rooms for specific users
is kept in ``account_data`` in an event of type ``m.direct``. The
is kept in `account_data` in an event of type `m.direct`. The
content of this event is an object where the keys are the user IDs
and values are lists of room ID strings of the 'direct' rooms for
that user ID.

6
data/event-schemas/schema/m.dummy.yaml
View file

@ -4,13 +4,13 @@ allOf:
description: |-
This event type is used to indicate new Olm sessions for end-to-end encryption.
Typically it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_
Typically it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_
event.
The event does not have any content associated with it. The sending client is expected
to send a key share request shortly after this message, causing the receiving client to
process this ``m.dummy`` event as the most recent event and using the keyshare request
to set up the session. The keyshare request and ``m.dummy`` combination should result
process this `m.dummy` event as the most recent event and using the keyshare request
to set up the session. The keyshare request and `m.dummy` combination should result
in the original sending client receiving keys over the newly established session.
properties:
content:

6
data/event-schemas/schema/m.forwarded_room_key.yaml
View file

@ -4,7 +4,7 @@ allOf:
description: |-
This event type is used to forward keys for end-to-end encryption. Typically
it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_
it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_
event.
properties:
content:
@ -49,8 +49,8 @@ properties:
Indicates that the key cannot be used to decrypt all the messages
from the session because a portion of the session was withheld as
described in `Reporting that decryption keys are withheld`_. This
object must include the ``code`` and ``reason`` properties from the
``m.room_key.withheld`` message that was received by the sender of
object must include the `code` and `reason` properties from the
`m.room_key.withheld` message that was received by the sender of
this message.
required:
- algorithm

6
data/event-schemas/schema/m.identity_server.yaml
View file

@ -11,10 +11,10 @@ properties:
base_url:
type: string
description: |-
The URL of the identity server the user prefers to use, or ``null``
The URL of the identity server the user prefers to use, or `null`
if the user does not want to use an identity server. This value is
similar in structure to the ``base_url`` for identity servers in the
``.well-known/matrix/client`` schema.
similar in structure to the `base_url` for identity servers in the
`.well-known/matrix/client` schema.
type:
enum:
- m.identity_server

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

@ -2,8 +2,8 @@
allOf:
- $ref: core-event-schema/event.yaml
description: |-
A map of users which are considered ignored is kept in ``account_data``
in an event type of ``m.ignored_user_list``.
A map of users which are considered ignored is kept in `account_data`
in an event type of `m.ignored_user_list`.
properties:
content:
type: object

14
data/event-schemas/schema/m.key.verification.accept.yaml
View file

@ -3,7 +3,7 @@ allOf:
- $ref: core-event-schema/event.yaml
description: |-
Accepts a previously sent ``m.key.verification.start`` message. Typically sent as a
Accepts a previously sent `m.key.verification.start` message. Typically sent as a
`to-device`_ event.
properties:
content:
@ -12,27 +12,27 @@ properties:
type: string
description: |-
An opaque identifier for the verification process. Must be the same as
the one used for the ``m.key.verification.start`` message.
the one used for the `m.key.verification.start` message.
key_agreement_protocol:
type: string
description: |-
The key agreement protocol the device is choosing to use, out of the
options in the ``m.key.verification.start`` message.
options in the `m.key.verification.start` message.
hash:
type: string
description: |-
The hash method the device is choosing to use, out of the options in
the ``m.key.verification.start`` message.
the `m.key.verification.start` message.
message_authentication_code:
type: string
description: |-
The message authentication code the device is choosing to use, out of
the options in the ``m.key.verification.start`` message.
the options in the `m.key.verification.start` message.
short_authentication_string:
type: array
description: |-
The SAS methods both devices involved in the verification process
understand. Must be a subset of the options in the ``m.key.verification.start``
understand. Must be a subset of the options in the `m.key.verification.start`
message.
items:
type: string
@ -42,7 +42,7 @@ properties:
description: |-
The hash (encoded as unpadded base64) of the concatenation of the device's
ephemeral public key (encoded as unpadded base64) and the canonical JSON
representation of the ``m.key.verification.start`` message.
representation of the `m.key.verification.start` message.
required:
- transaction_id
- method

30
data/event-schemas/schema/m.key.verification.cancel.yaml
View file

@ -14,8 +14,8 @@ properties:
reason:
type: string
description: |-
A human readable description of the ``code``. The client should only rely on this
string if it does not understand the ``code``.
A human readable description of the `code`. The client should only rely on this
string if it does not understand the `code`.
code:
type: string
# Note: this is not an enum because we go into detail about the different
@ -27,34 +27,34 @@ properties:
codes should use the Java package naming convention if not in the following
list:
``m.user``: The user cancelled the verification.
`m.user`: The user cancelled the verification.
``m.timeout``: The verification process timed out. Verification processes
`m.timeout`: The verification process timed out. Verification processes
can define their own timeout parameters.
``m.unknown_transaction``: The device does not know about the given transaction
`m.unknown_transaction`: The device does not know about the given transaction
ID.
``m.unknown_method``: The device does not know how to handle the requested
method. This should be sent for ``m.key.verification.start`` messages and
`m.unknown_method`: The device does not know how to handle the requested
method. This should be sent for `m.key.verification.start` messages and
messages defined by individual verification processes.
``m.unexpected_message``: The device received an unexpected message. Typically
`m.unexpected_message`: The device received an unexpected message. Typically
raised when one of the parties is handling the verification out of order.
``m.key_mismatch``: The key was not verified.
`m.key_mismatch`: The key was not verified.
``m.user_mismatch``: The expected user did not match the user verified.
`m.user_mismatch`: The expected user did not match the user verified.
``m.invalid_message``: The message received was invalid.
`m.invalid_message`: The message received was invalid.
``m.accepted``: A ``m.key.verification.request`` was accepted by a different
`m.accepted`: A `m.key.verification.request` was accepted by a different
device. The device receiving this error can ignore the verification request.
Clients should be careful to avoid error loops. For example, if a device sends
an incorrect message and the client returns ``m.invalid_message`` to which it
gets an unexpected response with ``m.unexpected_message``, the client should not
respond again with ``m.unexpected_message`` to avoid the other device potentially
an incorrect message and the client returns `m.invalid_message` to which it
gets an unexpected response with `m.unexpected_message`, the client should not
respond again with `m.unexpected_message` to avoid the other device potentially
sending another error response.
.. The above blank line is important for RST.

2
data/event-schemas/schema/m.key.verification.key.yaml
View file

@ -12,7 +12,7 @@ properties:
type: string
description: |-
An opaque identifier for the verification process. Must be the same as
the one used for the ``m.key.verification.start`` message.
the one used for the `m.key.verification.start` message.
key:
type: string
description: |-

4
data/event-schemas/schema/m.key.verification.mac.yaml
View file

@ -12,7 +12,7 @@ properties:
type: string
description: |-
An opaque identifier for the verification process. Must be the same as
the one used for the ``m.key.verification.start`` message.
the one used for the `m.key.verification.start` message.
mac:
type: object
description: |-
@ -24,7 +24,7 @@ properties:
keys:
type: string
description: |-
The MAC of the comma-separated, sorted, list of key IDs given in the ``mac``
The MAC of the comma-separated, sorted, list of key IDs given in the `mac`
property, encoded as unpadded base64.
required:
- transaction_id

14
data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml
View file

@ -3,7 +3,7 @@ allOf:
- $ref: core-event-schema/event.yaml
description: |-
Begins a SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event.
Begins a SAS key verification process using the `m.sas.v1` method. Typically sent as a `to-device`_ event.
properties:
content:
properties:
@ -16,7 +16,7 @@ properties:
description: |-
An opaque identifier for the verification process. Must be unique
with respect to the devices involved. Must be the same as the
``transaction_id`` given in the ``m.key.verification.request``
`transaction_id` given in the `m.key.verification.request`
if this process is originating from a request.
method:
type: string
@ -27,29 +27,29 @@ properties:
type: array
description: |-
The key agreement protocols the sending device understands. Should
include at least ``curve25519-hkdf-sha256``.
include at least `curve25519-hkdf-sha256`.
items:
type: string
hashes:
type: array
description: |-
The hash methods the sending device understands. Must include at least
``sha256``.
`sha256`.
items:
type: string
message_authentication_codes:
type: array
description: |-
The message authentication codes that the sending device understands.
Must include at least ``hkdf-hmac-sha256``.
Must include at least `hkdf-hmac-sha256`.
items:
type: string
short_authentication_string:
type: array
description: |-
The SAS methods the sending device (and the sending device's user)
understands. Must include at least ``decimal``. Optionally can include
``emoji``.
understands. Must include at least `decimal`. Optionally can include
`emoji`.
items:
type: string
enum: ["decimal", "emoji"]

10
data/event-schemas/schema/m.key.verification.start.yaml
View file

@ -3,9 +3,9 @@ allOf:
- $ref: core-event-schema/event.yaml
description: |-
Begins a key verification process. Typically sent as a `to-device`_ event. The ``method``
Begins a key verification process. Typically sent as a `to-device`_ event. The `method`
field determines the type of verification. The fields in the event will differ depending
on the ``method``. This definition includes fields that are in common among all variants.
on the `method`. This definition includes fields that are in common among all variants.
properties:
content:
properties:
@ -18,7 +18,7 @@ properties:
description: |-
An opaque identifier for the verification process. Must be unique
with respect to the devices involved. Must be the same as the
``transaction_id`` given in the ``m.key.verification.request``
`transaction_id` given in the `m.key.verification.request`
if this process is originating from a request.
method:
type: string
@ -28,8 +28,8 @@ properties:
type: string
description: |-
Optional method to use to verify the other user's key with. Applicable
when the ``method`` chosen only verifies one user's key. This field will
never be present if the ``method`` verifies keys both ways.
when the `method` chosen only verifies one user's key. This field will
never be present if the `method` verifies keys both ways.
required:
- from_device
- transaction_id

2
data/event-schemas/schema/m.receipt.yaml
View file

@ -18,7 +18,7 @@
"m.read": {
"type": "object",
"title": "Users",
"description": "A collection of users who have sent ``m.read`` receipts for this event.",
"description": "A collection of users who have sent `m.read` receipts for this event.",
"patternProperties": {
"^@": {
"type": "object",

2
data/event-schemas/schema/m.room.avatar.yaml
View file

@ -8,7 +8,7 @@ properties:
info:
allOf:
- $ref: core-event-schema/msgtype_infos/image_info.yaml
description: Metadata about the image referred to in ``url``.
description: Metadata about the image referred to in `url`.
url:
description: The URL to the image.
type: string

2
data/event-schemas/schema/m.room.canonical_alias.yaml
View file

@ -17,7 +17,7 @@ properties:
alt_aliases:
description: |
Alternative aliases the room advertises. This list can have aliases
despite the ``alias`` field being null, empty, or otherwise not present.
despite the `alias` field being null, empty, or otherwise not present.
type: array
items:
type: string

6
data/event-schemas/schema/m.room.create.yaml
View file

@ -6,13 +6,13 @@ properties:
content:
properties:
creator:
description: The ``user_id`` of the room creator. This is set by the homeserver.
description: The `user_id` of the room creator. This is set by the homeserver.
type: string
m.federate:
description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist.
description: Whether users on other servers can join this room. Defaults to `true` if key does not exist.
type: boolean
room_version:
description: The version of the room. Defaults to ``"1"`` if the key does not exist.
description: The version of the room. Defaults to `"1"` if the key does not exist.
type: string
predecessor:
description: A reference to the room this room replaces, if the previous room was upgraded.

4
data/event-schemas/schema/m.room.encryption.yaml
View file

@ -15,12 +15,12 @@ properties:
rotation_period_ms:
type: integer
description: |-
How long the session should be used before changing it. ``604800000``
How long the session should be used before changing it. `604800000`
(a week) is the recommended default.
rotation_period_msgs:
type: integer
description: |-
How many messages should be sent before changing the session. ``100`` is the
How many messages should be sent before changing the session. `100` is the
recommended default.
required:
- algorithm

2
data/event-schemas/schema/m.room.join_rules.yaml
View file

@ -1,7 +1,7 @@
---
allOf:
- $ref: core-event-schema/state_event.yaml
description: 'A room may be ``public`` meaning anyone can join the room without any prior action. Alternatively, it can be ``invite`` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, ``knock`` and ``private`` are reserved keywords which are not implemented.'
description: 'A room may be `public` meaning anyone can join the room without any prior action. Alternatively, it can be `invite` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, `knock` and `private` are reserved keywords which are not implemented.'
properties:
content:
properties:

48
data/event-schemas/schema/m.room.member.yaml
View file

@ -2,34 +2,34 @@
allOf:
- $ref: core-event-schema/state_event.yaml
description: |-
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
The following membership states are specified:
- ``invite`` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
- `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
- ``join`` - The user has joined the room (possibly after accepting an invite), and may participate in it.
- `join` - The user has joined the room (possibly after accepting an invite), and may participate in it.
- ``leave`` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
- `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
- ``ban`` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ``ban``).
- `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`).
- ``knock`` - This is a reserved word, which currently has no meaning.
- `knock` - This is a reserved word, which currently has no meaning.
The ``third_party_invite`` property will be set if this invite is an ``invite`` event and is the successor of an ``m.room.third_party_invite`` event, and absent otherwise.
The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise.
This event may also include an ``invite_room_state`` key inside the event's ``unsigned`` data.
If present, this contains an array of ``StrippedState`` Events. These events provide information
This event may also include an `invite_room_state` key inside the event's `unsigned` data.
If present, this contains an array of `StrippedState` Events. These events provide information
on a subset of state events such as the room name.
The user for which a membership applies is represented by the ``state_key``. Under some conditions,
the ``sender`` and ``state_key`` may not match - this may be interpreted as the ``sender`` affecting
the membership state of the ``state_key`` user.
The user for which a membership applies is represented by the `state_key`. Under some conditions,
the `sender` and `state_key` may not match - this may be interpreted as the `sender` affecting
the membership state of the `state_key` user.
The ``membership`` for a given user can change over time. The table below represents the various changes
The `membership` for a given user can change over time. The table below represents the various changes
over time and how clients and servers must interpret those changes. Previous membership can be retrieved
from the ``prev_content`` object on an event. If not present, the user's previous membership must be assumed
as ``leave``.
from the `prev_content` object on an event. If not present, the user's previous membership must be assumed
as `leave`.
.. TODO: Improve how this table is written? We use a csv-table to get around vertical header restrictions.
@ -37,12 +37,12 @@ description: |-
:header-rows: 1
:stub-columns: 1
"","to ``invite``","to ``join``","to ``leave``","to ``ban``","to ``knock``"
"from ``invite``","No change.","User joined the room.","If the ``state_key`` is the same as the ``sender``, the user rejected the invite. Otherwise, the ``state_key`` user had their invite revoked.","User was banned.","Not implemented."
"from ``join``","Must never happen.","``displayname`` or ``avatar_url`` changed.","If the ``state_key`` is the same as the ``sender``, the user left. Otherwise, the ``state_key`` user was kicked.","User was kicked and banned.","Not implemented."
"from ``leave``","New invitation sent.","User joined.","No change.","User was banned.","Not implemented."
"from ``ban``","Must never happen.","Must never happen.","User was unbanned.","No change.","Not implemented."
"from ``knock``","Not implemented.","Not implemented.","Not implemented.","Not implemented.","Not implemented."
"","to `invite`","to `join`","to `leave`","to `ban`","to `knock`"
"from `invite`","No change.","User joined the room.","If the `state_key` is the same as the `sender`, the user rejected the invite. Otherwise, the `state_key` user had their invite revoked.","User was banned.","Not implemented."
"from `join`","Must never happen.","`displayname` or `avatar_url` changed.","If the `state_key` is the same as the `sender`, the user left. Otherwise, the `state_key` user was kicked.","User was kicked and banned.","Not implemented."
"from `leave`","New invitation sent.","User joined.","No change.","User was banned.","Not implemented."
"from `ban`","Must never happen.","Must never happen.","User was unbanned.","No change.","Not implemented."
"from `knock`","Not implemented.","Not implemented.","Not implemented.","Not implemented.","Not implemented."
properties:
content:
@ -115,8 +115,8 @@ properties:
type: object
state_key:
description: |-
The ``user_id`` this membership event relates to. In all cases except for when ``membership`` is
``join``, the user ID sending the event does not need to match the user ID in the ``state_key``,
The `user_id` this membership event relates to. In all cases except for when `membership` is
`join`, the user ID sending the event does not need to match the user ID in the `state_key`,
unlike other events. Regular authorisation rules still apply.
type: string
type:
@ -129,7 +129,7 @@ properties:
- type: object
properties:
invite_room_state:
description: 'A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.'
description: 'A subset of the state of the room at the time of the invite, if `membership` is `invite`. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name` SHOULD be included.'
items:
$ref: "stripped_state.yaml"
type: array

4
data/event-schemas/schema/m.room.message$m.audio.yaml
View file

@ -9,13 +9,13 @@ properties:
description: "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'."
type: string
info:
description: Metadata for the audio clip referred to in ``url``.
description: Metadata for the audio clip referred to in `url`.
properties:
duration:
description: The duration of the audio in milliseconds.
type: integer
mimetype:
description: The mimetype of the audio e.g. ``audio/aac``.
description: The mimetype of the audio e.g. `audio/aac`.
type: string
size:
description: The size of the audio clip in bytes.

8
data/event-schemas/schema/m.room.message$m.emote.yaml
View file

@ -1,7 +1,7 @@
---
allOf:
- $ref: core-event-schema/room_event.yaml
description: "This message is similar to ``m.text`` except that the sender is 'performing' the action contained in the ``body`` key, similar to ``/me`` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular ``m.text`` messages."
description: "This message is similar to `m.text` except that the sender is 'performing' the action contained in the `body` key, similar to `/me` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular `m.text` messages."
properties:
content:
properties:
@ -14,12 +14,12 @@ properties:
type: string
format:
description: |-
The format used in the ``formatted_body``. Currently only
``org.matrix.custom.html`` is supported.
The format used in the `formatted_body`. Currently only
`org.matrix.custom.html` is supported.
type: string
formatted_body:
description: |-
The formatted version of the ``body``. This is required if ``format``
The formatted version of the `body`. This is required if `format`
is specified.
type: string
required:

6
data/event-schemas/schema/m.room.message$m.file.yaml
View file

@ -12,10 +12,10 @@ properties:
description: The original filename of the uploaded file.
type: string
info:
description: Information about the file referred to in ``url``.
description: Information about the file referred to in `url`.
properties:
mimetype:
description: The mimetype of the file e.g. ``application/msword``.
description: The mimetype of the file e.g. `application/msword`.
type: string
size:
description: The size of the file in bytes.
@ -34,7 +34,7 @@ properties:
thumbnail_info:
allOf:
- $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
description: Metadata about the image referred to in ``thumbnail_url``.
description: Metadata about the image referred to in `thumbnail_url`.
title: FileInfo
type: object
msgtype:

2
data/event-schemas/schema/m.room.message$m.image.yaml
View file

@ -11,7 +11,7 @@ properties:
info:
allOf:
- $ref: core-event-schema/msgtype_infos/image_info.yaml
description: Metadata about the image referred to in ``url``.
description: Metadata about the image referred to in `url`.
msgtype:
enum:
- m.image

2
data/event-schemas/schema/m.room.message$m.location.yaml
View file

@ -32,7 +32,7 @@ properties:
thumbnail_info:
allOf:
- $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
description: Metadata about the image referred to in ``thumbnail_url``.
description: Metadata about the image referred to in `thumbnail_url`.
title: LocationInfo
required:
- msgtype

8
data/event-schemas/schema/m.room.message$m.notice.yaml
View file

@ -1,7 +1,7 @@
---
allOf:
- $ref: core-event-schema/room_event.yaml
description: 'The ``m.notice`` type is primarily intended for responses from automated clients. An ``m.notice`` message must be treated the same way as a regular ``m.text`` message with two exceptions. Firstly, clients should present ``m.notice`` messages to users in a distinct manner, and secondly, ``m.notice`` messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.'
description: 'The `m.notice` type is primarily intended for responses from automated clients. An `m.notice` message must be treated the same way as a regular `m.text` message with two exceptions. Firstly, clients should present `m.notice` messages to users in a distinct manner, and secondly, `m.notice` messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.'
properties:
content:
properties:
@ -14,12 +14,12 @@ properties:
type: string
format:
description: |-
The format used in the ``formatted_body``. Currently only
``org.matrix.custom.html`` is supported.
The format used in the `formatted_body`. Currently only
`org.matrix.custom.html` is supported.
type: string
formatted_body:
description: |-
The formatted version of the ``body``. This is required if ``format``
The formatted version of the `body`. This is required if `format`
is specified.
type: string
required:

4
data/event-schemas/schema/m.room.message$m.server_notice.yaml
View file

@ -19,12 +19,12 @@ properties:
admin_contact:
description: |-
A URI giving a contact method for the server administrator. Required if the
notice type is ``m.server_notice.usage_limit_reached``.
notice type is `m.server_notice.usage_limit_reached`.
type: string
limit_type:
description: |-
The kind of usage limit the server has exceeded. Required if the notice type is
``m.server_notice.usage_limit_reached``.
`m.server_notice.usage_limit_reached`.
type: string
required:
- msgtype

6
data/event-schemas/schema/m.room.message$m.text.yaml
View file

@ -14,12 +14,12 @@ properties:
type: string
format:
description: |-
The format used in the ``formatted_body``. Currently only
``org.matrix.custom.html`` is supported.
The format used in the `formatted_body`. Currently only
`org.matrix.custom.html` is supported.
type: string
formatted_body:
description: |-
The formatted version of the ``body``. This is required if ``format``
The formatted version of the `body`. This is required if `format`
is specified.
type: string
required:

6
data/event-schemas/schema/m.room.message$m.video.yaml
View file

@ -9,7 +9,7 @@ properties:
description: "A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'."
type: string
info:
description: Metadata about the video clip referred to in ``url``.
description: Metadata about the video clip referred to in `url`.
properties:
duration:
description: The duration of the video in milliseconds.
@ -21,7 +21,7 @@ properties:
description: The width of the video in pixels.
type: integer
mimetype:
description: The mimetype of the video e.g. ``video/mp4``.
description: The mimetype of the video e.g. `video/mp4`.
type: string
size:
description: The size of the video in bytes.
@ -40,7 +40,7 @@ properties:
thumbnail_info:
allOf:
- $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
description: Metadata about the image referred to in ``thumbnail_url``.
description: Metadata about the image referred to in `thumbnail_url`.
title: VideoInfo
type: object
msgtype:

2
data/event-schemas/schema/m.room.message.feedback.yaml
View file

@ -1,7 +1,7 @@
---
allOf:
- $ref: core-event-schema/room_event.yaml
description: '**NB: Usage of this event is discouraged in favour of the** `receipts module`_. **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: ``delivered`` (sent when the event has been received) and ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` should reference the ``m.room.message`` event being acknowledged.'
description: '**NB: Usage of this event is discouraged in favour of the** `receipts module`_. **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: `delivered` (sent when the event has been received) and `read` (sent when the event has been observed by the end-user). The `target_event_id` should reference the `m.room.message` event being acknowledged.'
properties:
content:
properties:

4
data/event-schemas/schema/m.room.message.yaml
View file

@ -1,7 +1,7 @@
---
allOf:
- $ref: core-event-schema/room_event.yaml
description: 'This event is used when sending messages in a room. Messages are not limited to be text. The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc. The ``body`` key is text and MUST be used with every kind of ``msgtype`` as a fallback mechanism for when a client cannot render a message. This allows clients to display *something* even if it is just plain text.'
description: 'This event is used when sending messages in a room. Messages are not limited to be text. The `msgtype` key outlines the type of message, e.g. text, audio, image, video, etc. The `body` key is text and MUST be used with every kind of `msgtype` as a fallback mechanism for when a client cannot render a message. This allows clients to display *something* even if it is just plain text.'
properties:
content:
properties:
@ -9,7 +9,7 @@ properties:
description: The textual representation of this message.
type: string
msgtype:
description: 'The type of message, e.g. ``m.image``, ``m.text``'
description: 'The type of message, e.g. `m.image`, `m.text`'
type: string
required:
- msgtype

6
data/event-schemas/schema/m.room.name.yaml
View file

@ -7,12 +7,12 @@ description: |-
is a human-friendly string designed to be displayed to the end-user. The
room name is not unique, as multiple rooms can have the same room name set.
A room with an ``m.room.name`` event with an absent, null, or empty
``name`` field should be treated the same as a room with no ``m.room.name``
A room with an `m.room.name` event with an absent, null, or empty
`name` field should be treated the same as a room with no `m.room.name`
event.
An event of this type is automatically created when creating a room using
``/createRoom`` with the ``name`` key.
`/createRoom` with the `name` key.
properties:
content:
properties:

50
data/event-schemas/schema/m.room.power_levels.yaml
View file

@ -5,42 +5,42 @@ description: |-
This event specifies the minimum level a user must have in order to perform a
certain action. It also specifies the levels of each user in the room.
If a ``user_id`` is in the ``users`` list, then that ``user_id`` has the
If a `user_id` is in the `users` list, then that `user_id` has the
associated power level. Otherwise they have the default level
``users_default``. If ``users_default`` is not supplied, it is assumed to be
0. If the room contains no ``m.room.power_levels`` event, the room's creator has
`users_default`. If `users_default` is not supplied, it is assumed to be
0. If the room contains no `m.room.power_levels` event, the room's creator has
a power level of 100, and all other users have a power level of 0.
The level required to send a certain event is governed by ``events``,
``state_default`` and ``events_default``. If an event type is specified in
``events``, then the user must have at least the level specified in order to
The level required to send a certain event is governed by `events`,
`state_default` and `events_default`. If an event type is specified in
`events`, then the user must have at least the level specified in order to
send that event. If the event type is not supplied, it defaults to
``events_default`` for Message Events and ``state_default`` for State
`events_default` for Message Events and `state_default` for State
Events.
If there is no ``state_default`` in the ``m.room.power_levels`` event, the
``state_default`` is 50. If there is no ``events_default`` in the
``m.room.power_levels`` event, the ``events_default`` is 0. If the room
contains no ``m.room.power_levels`` event, *both* the ``state_default`` and
``events_default`` are 0.
If there is no `state_default` in the `m.room.power_levels` event, the
`state_default` is 50. If there is no `events_default` in the
`m.room.power_levels` event, the `events_default` is 0. If the room
contains no `m.room.power_levels` event, *both* the `state_default` and
`events_default` are 0.
The power level required to invite a user to the room, kick a user from the
room, ban a user from the room, or redact an event sent by another user, is
defined by ``invite``, ``kick``, ``ban``, and ``redact``, respectively. Each
defined by `invite`, `kick`, `ban`, and `redact`, respectively. Each
of these levels defaults to 50 if they are not specified in the
``m.room.power_levels`` event, or if the room contains no ``m.room.power_levels``
`m.room.power_levels` event, or if the room contains no `m.room.power_levels`
event.
**Note:**
As noted above, in the absence of an ``m.room.power_levels`` event, the
``state_default`` is 0, and all users are considered to have power level 0.
As noted above, in the absence of an `m.room.power_levels` event, the
`state_default` is 0, and all users are considered to have power level 0.
That means that **any** member of the room can send an
``m.room.power_levels`` event, changing the permissions in the room.
`m.room.power_levels` event, changing the permissions in the room.
Server implementations should therefore ensure that each room has an
``m.room.power_levels`` event as soon as it is created. See also the
documentation of the ``/createRoom`` API.
`m.room.power_levels` event as soon as it is created. See also the
documentation of the `/createRoom` API.
properties:
content:
@ -57,7 +57,7 @@ properties:
events_default:
description: |-
The default level required to send message events. Can be
overridden by the ``events`` key. Defaults to 0 if unspecified.
overridden by the `events` key. Defaults to 0 if unspecified.
type: integer
invite:
description: The level required to invite a user. Defaults to 50 if unspecified.
@ -71,30 +71,30 @@ properties:
state_default:
description: |-
The default level required to send state events. Can be overridden
by the ``events`` key. Defaults to 50 if unspecified.
by the `events` key. Defaults to 50 if unspecified.
type: integer
users:
additionalProperties:
type: integer
description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.
description: The power levels for specific users. This is a mapping from `user_id` to power level for that user.
title: User power levels
type: object
users_default:
description: |-
The default power level for every user in the room, unless their
``user_id`` is mentioned in the ``users`` key. Defaults to 0 if
`user_id` is mentioned in the `users` key. Defaults to 0 if
unspecified.
type: integer
notifications:
properties:
room:
type: integer
description: The level required to trigger an ``@room`` notification. Defaults to 50 if unspecified.
description: The level required to trigger an `@room` notification. Defaults to 50 if unspecified.
additionalProperties:
type: integer
description: |-
The power level requirements for specific notification types.
This is a mapping from ``key`` to power level for that notifications key.
This is a mapping from `key` to power level for that notifications key.
title: Notifications
type: object
type: object

2
data/event-schemas/schema/m.room.redaction.yaml
View file

@ -1,7 +1,7 @@
---
allOf:
- $ref: core-event-schema/room_event.yaml
description: 'This event is created by the server to describe which event has been redacted, by whom, and optionally why. The event that has been redacted is specified in the ``redacts`` event level key. Redacting an event means that all keys not required by the protocol are stripped off, allowing messages to be hidden or allowing admins to remove offensive or illegal content.'
description: 'This event is created by the server to describe which event has been redacted, by whom, and optionally why. The event that has been redacted is specified in the `redacts` event level key. Redacting an event means that all keys not required by the protocol are stripped off, allowing messages to be hidden or allowing admins to remove offensive or illegal content.'
properties:
content:
properties:

34
data/event-schemas/schema/m.room.server_acl.yaml
View file

@ -7,19 +7,19 @@ description: |-
server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts
list in order for the ACLs to remain effective.
The ``allow`` and ``deny`` lists are lists of globs supporting ``?`` and ``*``
The `allow` and `deny` lists are lists of globs supporting `?` and `*`
as wildcards. When comparing against the server ACLs, the suspect server's port
number must not be considered. Therefore ``evil.com``, ``evil.com:8448``, and
``evil.com:1234`` would all match rules that apply to ``evil.com``, for example.
number must not be considered. Therefore `evil.com`, `evil.com:8448`, and
`evil.com:1234` would all match rules that apply to `evil.com`, for example.
The ACLs are applied to servers when they make requests, and are applied in
the following order:
1. If there is no ``m.room.server_acl`` event in the room state, allow.
#. If the server name is an IP address (v4 or v6) literal, and ``allow_ip_literals``
is present and ``false``, deny.
#. If the server name matches an entry in the ``deny`` list, deny.
#. If the server name matches an entry in the ``allow`` list, allow.
1. If there is no `m.room.server_acl` event in the room state, allow.
#. If the server name is an IP address (v4 or v6) literal, and `allow_ip_literals`
is present and `false`, deny.
#. If the server name matches an entry in the `deny` list, deny.
#. If the server name matches an entry in the `allow` list, allow.
#. Otherwise, deny.
**Note:**
@ -28,17 +28,17 @@ description: |-
allowed to connect and interact with a given room.
**Warning:**
Failing to provide an ``allow`` rule of some kind will prevent **all**
Failing to provide an `allow` rule of some kind will prevent **all**
servers from participating in the room, including the sender. This renders
the room unusable. A common allow rule is ``[ "*" ]`` which would still
permit the use of the ``deny`` list without losing the room.
the room unusable. A common allow rule is `[ "*" ]` which would still
permit the use of the `deny` list without losing the room.
**Warning:**
All compliant servers must implement server ACLs. However, legacy or noncompliant
servers exist which do not uphold ACLs, and these MUST be manually appended to
the denied hosts list when setting an ACL to prevent them from leaking events from
banned servers into a room. Currently, the only way to determine noncompliant hosts is
to check the ``prev_events`` of leaked events, therefore detecting servers which
to check the `prev_events` of leaked events, therefore detecting servers which
are not upholding the ACLs. Server versions can also be used to try to detect hosts that
will not uphold the ACLs, although this is not comprehensive. Server ACLs were added
in Synapse v0.32.0, although other server implementations and versions exist in the world.
@ -54,15 +54,15 @@ properties:
True to allow server names that are IP address literals. False to
deny. Defaults to true if missing or otherwise not a boolean.
This is strongly recommended to be set to ``false`` as servers running
This is strongly recommended to be set to `false` as servers running
with IP literal names are strongly discouraged in order to require
legitimate homeservers to be backed by a valid registered domain name.
allow:
type: array
description: |-
The server names to allow in the room, excluding any port information.
Wildcards may be used to cover a wider range of hosts, where ``*``
matches zero or more characters and ``?`` matches exactly one character.
Wildcards may be used to cover a wider range of hosts, where `*`
matches zero or more characters and `?` matches exactly one character.
**This defaults to an empty list when not provided, effectively disallowing
every server.**
@ -72,8 +72,8 @@ properties:
type: array
description: |-
The server names to disallow in the room, excluding any port information.
Wildcards may be used to cover a wider range of hosts, where ``*``
matches zero or more characters and ``?`` matches exactly one character.
Wildcards may be used to cover a wider range of hosts, where `*`
matches zero or more characters and `?` matches exactly one character.
This defaults to an empty list when not provided.
items:

2
data/event-schemas/schema/m.room.third_party_invite.yaml
View file

@ -2,7 +2,7 @@
$schema: http://json-schema.org/draft-04/schema#
allOf:
- $ref: core-event-schema/state_event.yaml
description: "Acts as an ``m.room.member`` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room."
description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room."
properties:
content:
properties:

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

@ -1,7 +1,7 @@
---
allOf:
- $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.'
properties:
content:
properties:

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

@ -6,31 +6,31 @@ description: |-
This event type is used to indicate that the sender is not sharing room keys
with the recipient. It is sent as a to-device event.
Possible values for ``code`` include:
Possible values for `code` include:
* ``m.blacklisted``: the user/device was blacklisted.
* ``m.unverified``: the user/device was not verified, and the sender is only
* `m.blacklisted`: the user/device was blacklisted.
* `m.unverified`: the user/device was not verified, and the sender is only
sharing keys with verified users/devices.
* ``m.unauthorised``: the user/device is not allowed to have the key. For
* `m.unauthorised`: the user/device is not allowed to have the key. For
example, this could be sent in response to a key request if the user/device
was not in the room when the original message was sent.
* ``m.unavailable``: sent in reply to a key request if the device that the
* `m.unavailable`: sent in reply to a key request if the device that the
key is requested from does not have the requested key.
* ``m.no_olm``: an olm session could not be established.
* `m.no_olm`: an olm session could not be established.
In most cases, this event refers to a specific room key. The one exception to
this is when the sender is unable to establish an olm session with the
recipient. When this happens, multiple sessions will be affected. In order
to avoid filling the recipient\'s device mailbox, the sender should only send
one ``m.room_key.withheld`` message with no ``room_id`` nor ``session_id``
one `m.room_key.withheld` message with no `room_id` nor `session_id`
set. If the sender retries and fails to create an olm session again in the
future, it should not send another ``m.room_key.withheld`` message with a
``code`` of ``m.no_olm``, unless another olm session was previously
future, it should not send another `m.room_key.withheld` message with a
`code` of `m.no_olm`, unless another olm session was previously
established successfully. In response to receiving an
``m.room_key.withheld`` message with a ``code`` of ``m.no_olm``, the
recipient may start an olm session with the sender and send an ``m.dummy``
`m.room_key.withheld` message with a `code` of `m.no_olm`, the
recipient may start an olm session with the sender and send an `m.dummy`
message to notify the sender of the new olm session. The recipient may
assume that this ``m.room_key.withheld`` message applies to all encrypted
assume that this `m.room_key.withheld` message applies to all encrypted
room messages sent before it receives the message.
properties:
content:
@ -43,12 +43,12 @@ properties:
room_id:
type: string
description: |-
Required if ``code`` is not ``m.no_olm``. The room for the key that
Required if `code` is not `m.no_olm`. The room for the key that
this event is about.
session_id:
type: string
description: |-
Required of ``code`` is not ``m.no_olm``. The session ID of the key
Required of `code` is not `m.no_olm`. The session ID of the key
that this event is aboutis for.
sender_key:
type: string
@ -73,7 +73,7 @@ properties:
description: |-
A human-readable reason for why the key was not sent. The receiving
client should only use this string if it does not understand the
``code``.
`code`.
required:
- algorithm
- sender_key

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

@ -4,7 +4,7 @@ allOf:
description: |-
This event type is used to exchange keys for end-to-end encryption. Typically
it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ event.
it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_ event.
properties:
content:
properties:

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

@ -10,8 +10,8 @@ properties:
properties:
body:
description: |-
Information about the requested key. Required when ``action`` is
``request``.
Information about the requested key. Required when `action` is
`request`.
properties:
algorithm:
type: string

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

@ -15,11 +15,11 @@ properties:
allOf:
- $ref: core-event-schema/msgtype_infos/image_info.yaml
description: |-
Metadata about the image referred to in ``url`` including a thumbnail
Metadata about the image referred to in `url` including a thumbnail
representation.
url:
description: |-
The URL to the sticker image. This must be a valid ``mxc://`` URI.
The URL to the sticker image. This must be a valid `mxc://` URI.
type: string
required:
- body

2
data/event-schemas/schema/m.tag.yaml
View file

@ -24,7 +24,7 @@
"type": "number",
"format": "float",
"description":
"A number in a range ``[0,1]`` describing a relative position of the room under the given tag."
"A number in a range `[0,1]` describing a relative position of the room under the given tag."
}
}
}

12
data/event-schemas/schema/stripped_state.yaml
View file

@ -21,21 +21,21 @@
title: StrippedState
type: object
description: |-
A stripped down state event, with only the ``type``, ``state_key``,
``sender``, and ``content`` keys.
A stripped down state event, with only the `type`, `state_key`,
`sender`, and `content` keys.
properties:
content:
description: The ``content`` for the event.
description: The `content` for the event.
title: EventContent
type: object
state_key:
description: The ``state_key`` for the event.
description: The `state_key` for the event.
type: string
type:
description: The ``type`` for the event.
description: The `type` for the event.
type: string
sender:
description: The ``sender`` for the event.
description: The `sender` for the event.
type: string
required:
- type