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

18
data/api/server-server/backfill.yaml
View file

@ -32,8 +32,8 @@ paths:
summary: Retrieves the events which precede the given event
description: |-
Retrieves a sliding-window history of previous PDUs that occurred in the given room.
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs given in ``v`` and
the PDUs that preceded them are retrieved, up to the total number given by the ``limit``.
Starting from the PDU ID(s) given in the `v` argument, the PDUs given in `v` and
the PDUs that preceded them are retrieved, up to the total number given by the `limit`.
operationId: backfillRoom
security:
- signedRequest: []
@ -65,12 +65,12 @@ paths:
event(s), up to the given limit.
**Note:**
Though the PDU definitions require that ``prev_events`` and ``auth_events`` be limited
Though the PDU definitions require that `prev_events` and `auth_events` be limited
in number, the response of backfill MUST NOT be validated on these specific restrictions.
Due to historical reasons, it is possible that events which were previously accepted
would now be rejected by these limitations. The events should be rejected per usual by
the ``/send``, ``/get_missing_events``, and remaining endpoints.
the `/send`, `/get_missing_events`, and remaining endpoints.
schema:
$ref: "definitions/unlimited_pdu_transaction.yaml"
"/get_missing_events/{roomId}":
@ -78,8 +78,8 @@ paths:
summary: Retrieves events that the sender is missing
description: |-
Retrieves previous events that the sender is missing. This is done by doing a breadth-first
walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events``
and stopping at the ``limit``.
walk of the `prev_events` for the `latest_events`, ignoring any events in `earliest_events`
and stopping at the `limit`.
operationId: getMissingPreviousEvents
security:
- signedRequest: []
@ -107,7 +107,7 @@ paths:
type: array
description: |-
The latest event IDs that the sender already has. These are skipped when retrieving
the previous events of ``latest_events``.
the previous events of `latest_events`.
items:
type: string
example: ["$missing_event:example.org"]
@ -121,8 +121,8 @@ paths:
responses:
200:
description: |-
The previous events for ``latest_events``, excluding any ``earliest_events``, up to the
provided ``limit``.
The previous events for `latest_events`, excluding any `earliest_events`, up to the
provided `limit`.
schema:
type: object
properties:

6
data/api/server-server/definitions/event-schemas/m.device_list_update.yaml
View file

@ -32,7 +32,7 @@ allOf:
edu_type:
type: enum
enum: ['m.device_list_update']
description: The string ``m.device_list_update``.
description: The string `m.device_list_update`.
example: "m.device_list_update"
content:
type: object
@ -57,7 +57,7 @@ allOf:
type: integer
description: |-
An ID sent by the server for this update, unique for a given
user_id. Used to identify any gaps in the sequence of ``m.device_list_update``
user_id. Used to identify any gaps in the sequence of `m.device_list_update`
EDUs broadcast by a server.
example: 6
prev_id:
@ -67,7 +67,7 @@ allOf:
which have not been referred to already in an EDU's prev_id field. If the
receiving server does not recognise any of the prev_ids, it means an EDU
has been lost and the server should query a snapshot of the device list
via ``/user/keys/query`` in order to correctly interpret future ``m.device_list_update``
via `/user/keys/query` in order to correctly interpret future `m.device_list_update`
EDUs. May be missing or empty for the first EDU in a sequence.
items:
type: integer

4
data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml
View file

@ -25,7 +25,7 @@ allOf:
edu_type:
type: enum
enum: ['m.direct_to_device']
description: The string ``m.direct_to_device``.
description: The string `m.direct_to_device`.
example: "m.direct_to_device"
content:
type: object
@ -50,7 +50,7 @@ allOf:
description: |-
The contents of the messages to be sent. These are arranged in
a map of user IDs to a map of device IDs to message bodies.
The device ID may also be ``*``, meaning all known devices for the user.
The device ID may also be `*`, meaning all known devices for the user.
additionalProperties:
type: object
title: User Devices

6
data/api/server-server/definitions/event-schemas/m.presence.yaml
View file

@ -23,7 +23,7 @@ allOf:
edu_type:
type: enum
enum: ['m.presence']
description: The string ``m.presence``
description: The string `m.presence`
example: "m.presence"
content:
type: object
@ -63,8 +63,8 @@ allOf:
type: boolean
description: |-
True if the user is likely to be interacting with their
client. This may be indicated by the user having a
``last_active_ago`` within the last few minutes. Defaults
client. This may be indicated by the user having a
`last_active_ago` within the last few minutes. Defaults
to false.
example: true
required: ['user_id', 'presence', 'last_active_ago']

2
data/api/server-server/definitions/event-schemas/m.receipt.yaml
View file

@ -26,7 +26,7 @@ allOf:
edu_type:
type: enum
enum: ['m.receipt']
description: The string ``m.receipt``
description: The string `m.receipt`
example: "m.receipt"
content:
type: object

2
data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml
View file

@ -24,7 +24,7 @@ allOf:
edu_type:
type: enum
enum: ['m.signing_key_update']
description: The string ``m.signing_update``.
description: The string `m.signing_update`.
example: "m.signing_key_update"
content:
type: object

2
data/api/server-server/definitions/event-schemas/m.typing.yaml
View file

@ -22,7 +22,7 @@ allOf:
edu_type:
type: enum
enum: ['m.typing']
description: The string ``m.typing``
description: The string `m.typing`
example: "m.typing"
content:
type: object

8
data/api/server-server/definitions/invite_event.yaml
View file

@ -22,7 +22,7 @@ allOf:
sender:
type: string
description: |-
The matrix ID of the user who sent the original ``m.room.third_party_invite``.
The matrix ID of the user who sent the original `m.room.third_party_invite`.
example: "@someone:example.org"
origin:
type: string
@ -35,7 +35,7 @@ allOf:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -46,12 +46,12 @@ allOf:
title: Membership Event Content
description: |-
The content of the event, matching what is available in the
`Client-Server API`_. Must include a ``membership`` of ``invite``.
`Client-Server API`_. Must include a `membership` of `invite`.
example: {"membership": "invite"}
properties:
membership:
type: string
description: The value ``invite``.
description: The value `invite`.
example: "invite"
required: ['membership']
required:

14
data/api/server-server/definitions/keys.yaml
View file

@ -26,10 +26,10 @@ properties:
description: |-
Public keys of the homeserver for verifying digital signatures.
The object's key is the algorithm and version combined (``ed25519`` being the
algorithm and ``abc123`` being the version in the example below). Together,
The object's key is the algorithm and version combined (`ed25519` being the
algorithm and `abc123` being the version in the example below). Together,
this forms the Key ID. The version must have characters matching the regular
expression ``[a-zA-Z0-9_]``.
expression `[a-zA-Z0-9_]`.
additionalProperties:
type: object
title: Verify Key
@ -49,10 +49,10 @@ properties:
description: |-
The public keys that the server used to use and when it stopped using them.
The object's key is the algorithm and version combined (``ed25519`` being the
algorithm and ``0ldK3y`` being the version in the example below). Together,
The object's key is the algorithm and version combined (`ed25519` being the
algorithm and `0ldK3y` being the version in the example below). Together,
this forms the Key ID. The version must have characters matching the regular
expression ``[a-zA-Z0-9_]``.
expression `[a-zA-Z0-9_]`.
additionalProperties:
type: object
title: Old Verify Key
@ -76,7 +76,7 @@ properties:
signatures:
type: object
description: |-
Digital signatures for this object signed using the ``verify_keys``.
Digital signatures for this object signed using the `verify_keys`.
The signature is calculated using the process described at `Signing
JSON`_.

2
data/api/server-server/definitions/security.yaml
View file

@ -14,6 +14,6 @@
signedRequest:
type: apiKey
description: |-
The ``Authorization`` header defined in the `Authentication`_ section.
The `Authorization` header defined in the `Authentication`_ section.
name: Authorization
in: header

2
data/api/server-server/definitions/transaction.yaml
View file

@ -20,7 +20,7 @@ properties:
origin:
type: string
description: |-
The ``server_name`` of the homeserver sending this transaction.
The `server_name` of the homeserver sending this transaction.
example: "example.org"
origin_server_ts:
type: integer

8
data/api/server-server/definitions/unsigned_pdu_base.yaml
View file

@ -27,7 +27,7 @@ properties:
example: "@someone:matrix.org"
origin:
type: string
description: The ``server_name`` of the homeserver that created this event.
description: The `server_name` of the homeserver that created this event.
example: "matrix.org"
origin_server_ts:
type: integer
@ -42,7 +42,7 @@ properties:
type: string
description: |-
If this key is present, the event is a state event, and it will replace previous events
with the same ``type`` and ``state_key`` in the room state.
with the same `type` and `state_key` in the room state.
example: "my_key"
content:
type: object
@ -77,7 +77,7 @@ properties:
depth:
type: integer
description: |-
The maximum depth of the ``prev_events``, plus one. Must be less than the
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
@ -117,7 +117,7 @@ properties:
type: object
title: UnsignedData
description: |-
Additional data added by the origin server but not covered by the ``signatures``. More
Additional data added by the origin server but not covered by the `signatures`. More
keys than those defined here may be used.
example: {"key": "value"}
properties:

2
data/api/server-server/events.yaml
View file

@ -94,7 +94,7 @@ paths:
summary: Get all the state event IDs of a given room
description: |-
Retrieves a snapshot of a room's state at a given event, in the form of
event IDs. This performs the same function as calling ``/state/{roomId}``,
event IDs. This performs the same function as calling `/state/{roomId}`,
however this returns just the event IDs rather than the full events.
operationId: getRoomStateIds
security:

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

@ -36,8 +36,8 @@ paths:
room by the inviting homeserver.
Servers should prefer to use the v2 API for invites instead of the v1 API. Servers
which receive a v1 invite request must assume that the room version is either ``"1"``
or ``"2"``.
which receive a v1 invite request must assume that the room version is either `"1"`
or `"2"`.
Note that events have a different format depending on the room version - check the
`room version specification`_ for precise event formats. **The request and response
@ -113,7 +113,7 @@ paths:
maxItems: 2
items:
- type: integer
description: The value ``200``.
description: The value `200`.
example: 200
- type: object
description: An object containing the signed invite event.

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

@ -164,7 +164,7 @@ paths:
400:
description: |-
The request is invalid or the room the server is attempting
to join has a version that is not listed in the ``ver``
to join has a version that is not listed in the `ver`
parameters.
The error should be passed through to clients so that they
@ -177,8 +177,8 @@ paths:
room_version:
type: string
description: |-
The version of the room. Required if the ``errcode``
is ``M_INCOMPATIBLE_ROOM_VERSION``.
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",

20
data/api/server-server/joins-v1.yaml
View file

@ -57,7 +57,7 @@ paths:
name: ver
description: |-
The room versions the sending server has support for. Defaults
to ``[1]``.
to `[1]`.
x-example: ["1", "2"]
responses:
200:
@ -99,7 +99,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -113,7 +113,7 @@ paths:
properties:
membership:
type: string
description: The value ``join``.
description: The value `join`.
example: "join"
required: ['membership']
required:
@ -141,7 +141,7 @@ paths:
400:
description: |-
The request is invalid or the room the server is attempting
to join has a version that is not listed in the ``ver``
to join has a version that is not listed in the `ver`
parameters.
The error should be passed through to clients so that they
@ -154,8 +154,8 @@ paths:
room_version:
type: string
description: |-
The version of the room. Required if the ``errcode``
is ``M_INCOMPATIBLE_ROOM_VERSION``.
The version of the room. Required if the `errcode`
is `M_INCOMPATIBLE_ROOM_VERSION`.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
@ -177,7 +177,7 @@ paths:
summary: Submit a signed join event to a resident server
description: |-
**Note:**
Servers should instead prefer to use the v2 ``/send_join`` endpoint.
Servers should instead prefer to use the v2 `/send_join` endpoint.
Submits a signed join event to the resident server for it
to accept it into the room's graph. Note that events have
@ -224,7 +224,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -238,7 +238,7 @@ paths:
properties:
membership:
type: string
description: The value ``join``.
description: The value `join`.
example: "join"
required: ['membership']
required:
@ -269,7 +269,7 @@ paths:
maxItems: 2
items:
- type: integer
description: The value ``200``.
description: The value `200`.
example: 200
- $ref: "./definitions/send_join_response.yaml"
examples:

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

@ -87,7 +87,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -101,7 +101,7 @@ paths:
properties:
membership:
type: string
description: The value ``join``.
description: The value `join`.
example: "join"
required: ['membership']
required:

6
data/api/server-server/keys_query.yaml
View file

@ -93,11 +93,11 @@ paths:
server_keys:
type: object
description: |-
The query criteria. The outer ``string`` key on the object is the
server name (eg: ``matrix.org``). The inner ``string`` key is the
The query criteria. The outer `string` key on the object is the
server name (eg: `matrix.org`). The inner `string` key is the
Key ID to query for the particular server. If no key IDs are given
to be queried, the notary server should query for all keys. If no
servers are given, the notary server must return an empty ``server_keys``
servers are given, the notary server must return an empty `server_keys`
array in the response.
The notary server may return multiple keys regardless of the Key IDs

14
data/api/server-server/leaving-v1.yaml
View file

@ -53,7 +53,7 @@ paths:
responses:
200:
description: |-
A template to be used to call ``/send_leave``. Note that
A template to be used to call `/send_leave`. Note that
events have a different format depending on the room version - check the
`room version specification`_ for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
@ -90,7 +90,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -104,7 +104,7 @@ paths:
properties:
membership:
type: string
description: The value ``leave``.
description: The value `leave`.
example: "leave"
required: ['membership']
required:
@ -144,7 +144,7 @@ paths:
summary: Submit a signed leave event to a resident server
description: |-
**Note:**
Servers should instead prefer to use the v2 ``/send_leave`` endpoint.
Servers should instead prefer to use the v2 `/send_leave` endpoint.
Submits a signed leave event to the resident server for it
to accept it into the room's graph. Note that events have
@ -191,7 +191,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -205,7 +205,7 @@ paths:
properties:
membership:
type: string
description: The value ``leave``.
description: The value `leave`.
example: "leave"
required: ['membership']
depth:
@ -242,7 +242,7 @@ paths:
maxItems: 2
items:
- type: integer
description: The value ``200``.
description: The value `200`.
example: 200
- type: object
title: Empty Object

4
data/api/server-server/leaving-v2.yaml
View file

@ -87,7 +87,7 @@ paths:
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
description: The value `m.room.member`.
example: "m.room.member"
state_key:
type: string
@ -101,7 +101,7 @@ paths:
properties:
membership:
type: string
description: The value ``leave``.
description: The value `leave`.
example: "leave"
required: ['membership']
depth:

6
data/api/server-server/public_rooms.yaml
View file

@ -61,7 +61,7 @@ paths:
type: string
description: |-
The specific third party network/protocol to request from the homeserver.
Can only be used if ``include_all_networks`` is false.
Can only be used if `include_all_networks` is false.
x-example: "irc"
responses:
200:
@ -77,7 +77,7 @@ paths:
of joined members, with the largest rooms first.
Note that this endpoint receives and returns the same format that is seen
in the Client-Server API's ``POST /publicRooms`` endpoint.
in the Client-Server API's `POST /publicRooms` endpoint.
operationId: queryPublicRooms
security:
- signedRequest: []
@ -122,7 +122,7 @@ paths:
type: string
description: |-
The specific third party network/protocol to request from the
homeserver. Can only be used if ``include_all_networks`` is false.
homeserver. Can only be used if `include_all_networks` is false.
example: "irc"
example: {
"limit": 10,

6
data/api/server-server/query.yaml
View file

@ -137,13 +137,13 @@ paths:
responses:
200:
description: |-
The profile for the user. If a ``field`` is specified in the request, only the
matching field should be included in the response. If no ``field`` was specified,
The profile for the user. If a `field` is specified in the request, only the
matching field should be included in the response. If no `field` was specified,
the response should include the fields of the user's profile that can be made
public, such as the display name and avatar.
If the user does not have a particular field set on their profile, the server
should exclude it from the response body or give it the value ``null``.
should exclude it from the response body or give it the value `null`.
schema:
type: object
properties:

12
data/api/server-server/third_party_invite.yaml
View file

@ -31,7 +31,7 @@ paths:
put:
summary: Request a server to auth a third party invite event
description: |-
The receiving server will verify the partial ``m.room.member`` event
The receiving server will verify the partial `m.room.member` event
given in the request body. If valid, the receiving server will issue
an invite as per the `Inviting to a room`_ section before returning a
response to this request.
@ -48,14 +48,14 @@ paths:
- in: body
name: body
type: object
description: A partial ``m.room.member`` event
description: A partial `m.room.member` event
required: true
schema:
type: object
properties:
type:
type: string
description: The event type. Must be ``m.room.member``
description: The event type. Must be `m.room.member`
example: "m.room.member"
room_id:
type: string
@ -66,7 +66,7 @@ paths:
sender:
type: string
description: |-
The user ID of the user who sent the original ``m.room.third_party_invite``
The user ID of the user who sent the original `m.room.third_party_invite`
event.
example: "@joe:matrix.org"
state_key:
@ -80,7 +80,7 @@ paths:
properties:
membership:
type: string
description: The membership state. Must be ``invite``
description: The membership state. Must be `invite`
example: invite
third_party_invite:
type: object
@ -288,7 +288,7 @@ paths:
type: object
title: Identity Server Signature
description: |-
The signature from the identity server. The ``string`` key
The signature from the identity server. The `string` key
is the identity server's domain name, such as vector.im
additionalProperties:
type: object

2
data/api/server-server/transactions.yaml
View file

@ -36,7 +36,7 @@ paths:
transaction body will be processed.
The sending server must wait and retry for a 200 OK response before sending a
transaction with a different ``txnId`` to the receiving server.
transaction with a different `txnId` to the receiving server.
Note that events have a different format depending on the room version - check
the `room version specification`_ for precise event formats.

4
data/api/server-server/user_devices.yaml
View file

@ -58,8 +58,8 @@ paths:
type: integer
description: |-
A unique ID for a given user_id which describes the version of
the returned device list. This is matched with the ``stream_id``
field in ``m.device_list_update`` EDUs in order to incrementally
the returned device list. This is matched with the `stream_id`
field in `m.device_list_update` EDUs in order to incrementally
update the returned device_list.
example: 5
devices:

10
data/api/server-server/user_keys.yaml
View file

@ -72,7 +72,7 @@ paths:
type: object
description: |-
One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
map from devices to a map from `<algorithm>:<key_id>` to the key object.
See the `Client-Server Key Algorithms`_ section for more information on
the Key Object format.
@ -158,7 +158,7 @@ paths:
Information on the queried devices. A map from user ID, to a
map from device ID to device information. For each device,
the information returned will be the same as uploaded via
``/keys/upload``, with the addition of an ``unsigned``
`/keys/upload`, with the addition of an `unsigned`
property.
additionalProperties:
type: object
@ -184,8 +184,8 @@ paths:
Information on the master cross-signing keys of the queried users.
A map from user ID, to master key information. For each key, the
information returned will be the same as uploaded via
``/keys/device_signing/upload``, along with the signatures
uploaded via ``/keys/signatures/upload`` that the user is
`/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the user is
allowed to see.
additionalProperties:
allOf:
@ -205,7 +205,7 @@ paths:
Information on the self-signing keys of the queried users. A map
from user ID, to self-signing key information. For each key, the
information returned will be the same as uploaded via
``/keys/device_signing/upload``.
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: ../client-server/definitions/cross_signing_key.yaml

4
data/api/server-server/wellknown.yaml
View file

@ -33,8 +33,8 @@ paths:
responses:
200:
description:
The delegated server information. The ``Content-Type`` for this response SHOULD
be ``application/json``, however servers parsing the response should assume that
The delegated server information. The `Content-Type` for this response SHOULD
be `application/json`, however servers parsing the response should assume that
the body is JSON regardless of type. Failures parsing the JSON or invalid data
provided in the resulting parsed JSON should not result in discovery failure -
consult the server discovery process for information on how to continue.