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

Merge remote-tracking branch 'origin/master' into cross-signing-spec

Browse source
This commit is contained in:
Hubert Chathi 2020-05-29 17:25:19 -04:00
commit ec0b9badc7
70 changed files with 1748 additions and 298 deletions
Download patch file Download diff file Expand all files Collapse all files

2
api/client-server/admin.yaml
View file

@ -82,7 +82,7 @@ paths:
devices:
type: object
description: |-
Each key is an identitfier for one of the user's devices.
Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo

16
api/client-server/create_room.yaml
View file

@ -38,20 +38,26 @@ paths:
the new room, including checking power levels for each event. It MUST
apply the events implied by the request in the following order:
0. A default ``m.room.power_levels`` event, giving the room creator
1. The ``m.room.create`` event itself. Must be the first event in the
room.
2. An ``m.room.member`` event for the creator to join the room. This is
needed so the remaining events can be sent.
3. A default ``m.room.power_levels`` event, giving the room creator
(and not other members) permission to send state events. Overridden
by the ``power_level_content_override`` parameter.
1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
4. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
``m.room.history_visibility``, and ``m.room.guest_access`` state events.
2. Events listed in ``initial_state``, in the order that they are
5. Events listed in ``initial_state``, in the order that they are
listed.
3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
state events).
4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
``membership: invite`` and ``m.room.third_party_invite``).
The available presets do the following with respect to room state:

1
api/client-server/definitions/device_keys.yaml
View file

@ -47,6 +47,7 @@ properties:
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
signatures:
type: object
title: Signatures
description: |-
Signatures for the device key object. A map from user ID, to a map from
``<algorithm>:<device_id>`` to the signature.

4
api/client-server/definitions/third_party_signed.yaml
View file

@ -33,6 +33,10 @@ properties:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
additionalProperties:
type: object
additionalProperties:
type: string
example: {
"example.org": {
"ed25519:0": "some9signature"

82
api/client-server/directory.yaml
View file

@ -19,7 +19,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -27,7 +27,7 @@ produces:
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/room/{roomAlias}":
"/directory/room/{roomAlias}":
put:
summary: Create a new mapping from room alias to room ID.
operationId: setRoomAlias
@ -129,7 +129,16 @@ paths:
description: |-
Remove a mapping of room alias to room ID.
Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
Servers may choose to implement additional access control checks here, for instance that
room aliases can only be deleted by their creator or a server administrator.
.. Note::
Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias``
state event in the room when an alias is removed. Servers which choose to update the
canonical alias event are recommended to, in addition to their other relevant permission
checks, delete the alias and return a successful response even if the user does not
have permission to update the ``m.room.canonical_alias`` event.
operationId: deleteRoomAlias
security:
- accessToken: []
@ -159,3 +168,70 @@ paths:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
"/rooms/{roomId}/aliases":
get:
summary: Get a list of local aliases on a given room.
description: |-
Get a list of aliases maintained by the local server for the
given room.
This endpoint can be called by users who are in the room (external
users receive an ``M_FORBIDDEN`` error response). If the room's
``m.room.history_visibility`` maps to ``world_readable``, any
user can call this endpoint.
Servers may choose to implement additional access control checks here,
such as allowing server administrators to view aliases regardless of
membership.
.. Note::
Clients are recommended not to display this list of aliases prominently
as they are not curated, unlike those listed in the ``m.room.canonical_alias``
state event.
operationId: getLocalAliases
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID to find local aliases of.
required: true
x-example: "!abc123:example.org"
responses:
200:
description: |-
The list of local aliases for the room.
examples:
application/json: {
"aliases": [
"#somewhere:example.com",
"#another:example.com",
"#hat_trick:example.com"
]
}
schema:
type: object
properties:
aliases:
type: array
description: The server's local aliases on the room. Can be empty.
items:
type: string
required: ['aliases']
403:
description: The user is not permitted to retrieve the list of local aliases for the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not a member of the room."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room directory

2
api/client-server/keys.yaml
View file

@ -102,7 +102,7 @@ paths:
responses:
200:
description:
The provided keys were sucessfully uploaded.
The provided keys were successfully uploaded.
schema:
type: object
properties:

13
api/client-server/registration.yaml
View file

@ -328,8 +328,8 @@ paths:
The homeserver may change the flows available depending on whether a
valid access token is provided. The homeserver SHOULD NOT revoke the
access token provided in the request, however all other access tokens
for the user should be revoked if the request succeeds.
access token provided in the request. Whether other access tokens for
the user are revoked depends on the request parameters.
security:
- accessToken: []
operationId: changePassword
@ -343,6 +343,15 @@ paths:
type: string
description: The new password for the account.
example: "ihatebananas"
logout_devices:
type: boolean
description: |-
Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true.
When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_
for the user's remaining devices.
example: true
auth:
description: |-
Additional authentication information for the user-interactive authentication API.

2
api/client-server/room_send.yaml
View file

@ -85,5 +85,7 @@ paths:
type: string
description: |-
A unique identifier for the event.
required:
- event_id
tags:
- Room participation

26
api/client-server/room_state.yaml
View file

@ -45,6 +45,12 @@ paths:
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
If the event type being sent is ``m.room.canonical_alias`` servers
SHOULD ensure that any new aliases being listed in the event are valid
per their grammar/syntax and that they point to the room ID where the
state event is to be sent. Servers do not validate aliases which are
being removed or are already present in the state event.
operationId: setRoomStateWithKey
security:
- accessToken: []
@ -92,6 +98,8 @@ paths:
type: string
description: |-
A unique identifier for the event.
required:
- event_id
403:
description: |-
The sender doesn't have permission to send the event into the room.
@ -102,5 +110,23 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
400:
description: |-
The sender's request is malformed.
Some example error codes include:
* ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias``
event have invalid syntax.
* ``M_BAD_ALIAS``: One or more aliases within the ``m.room.canonical_alias`` event
do not point to the room ID for which the state event is to be sent to.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_BAD_ALIAS",
"error": "The alias '#hello:example.org' does not point to this room."
}
tags:
- Room participation

8
api/openapi_extensions.md
View file

@ -43,3 +43,11 @@ doesn't work, as in the following example:
properties:
...
```
## OpenAPI 3's "2xx" format for response codes
<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
In some cases, the schema will have HTTP response code definitions like
`2xx`, `3xx`, and `4xx`. These indicate that a response code within those
ranges (`2xx` = `200` to `299`) is valid for the schema.

12
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 that preceded it
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: []
@ -63,6 +63,14 @@ paths:
description: |-
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
.. Note::
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.
schema:
$ref: "definitions/unlimited_pdu_transaction.yaml"
"/get_missing_events/{roomId}":

22
api/server-server/definitions/keys.yaml
View file

@ -20,7 +20,6 @@ properties:
server_name:
type: string
description: DNS name of the homeserver.
required: true
example: "example.org"
verify_keys:
type: object
@ -31,7 +30,6 @@ properties:
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_]``.
required: true
additionalProperties:
type: object
title: Verify Key
@ -44,8 +42,8 @@ properties:
key:
type: string
description: The `Unpadded Base64`_ encoded key.
required: true
example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
required: ["key"]
old_verify_keys:
type: object
description: |-
@ -69,27 +67,24 @@ properties:
type: integer
format: int64
description: POSIX timestamp in milliseconds for when this key expired.
required: true
example: 1532645052628
key:
type: string
description: The `Unpadded Base64`_ encoded key.
required: true
example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
required: ["expired_ts", "key"]
signatures:
type: object
description: Digital signatures for this object signed using the ``verify_keys``.
description: |-
Digital signatures for this object signed using the ``verify_keys``.
The signature is calculated using the process described at `Signing
JSON`_.
title: Signatures
additionalProperties:
type: object
title: Signed Server
example: {
"example.org": {
"ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
}
}
additionalProperties:
type: string
name: Encoded Signature Verification Key
valid_until_ts:
type: integer
format: int64
@ -103,3 +98,4 @@ properties:
publishes a key which is valid for a significant amount of time without a way
for the homeserver owner to revoke it.
example: 1052262000000
required: ["server_name", "verify_keys"]

6
api/server-server/definitions/pdu_v3.yaml
View file

@ -32,6 +32,10 @@ allOf:
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: ["$base64EncodedHash", "$AnotherEvent"]
prev_events:
type: array
@ -41,6 +45,8 @@ allOf:
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: ["$base64EncodedHash", "$AnotherEvent"]
hashes:
type: object

6
api/server-server/definitions/pdu_v4.yaml
View file

@ -32,6 +32,10 @@ allOf:
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
@ -41,6 +45,8 @@ allOf:
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

58
api/server-server/definitions/send_join_response.yaml Normal file
View file

@ -0,0 +1,58 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: |-
The auth chain for the entire current room state prior to the join event.
Note that events have a different format depending on the room version - check the
`room version specification`_ for precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "../examples/minimal_pdu.json"
state:
type: array
description: |-
The resolved current room state prior to the join event.
The event format varies depending on the room version - check the `room version specification`_
for precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "../examples/minimal_pdu.json"
required: ["auth_chain", "state", "origin"]

6
api/server-server/definitions/unsigned_pdu_base.yaml
View file

@ -53,6 +53,8 @@ properties:
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
@ -84,6 +86,10 @@ properties:
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

55
api/server-server/joins.yaml → api/server-server/joins-v1.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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.
@ -62,7 +63,7 @@ paths:
200:
description: |-
A template to be used for the rest of the `Joining Rooms`_ handshake. Note that
events have a different format depending on the room version - check the
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
required fields for a PDU.**
@ -165,14 +166,18 @@ paths:
put:
summary: Submit a signed join event to a resident server
description: |-
.. Note::
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
a different format depending on the room version - check
a different format depending on the room version - check
the `room version specification`_ for precise event formats.
**The request and response body here describes the common
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendJoin
operationId: sendJoinV1
security:
- signedRequest: []
parameters:
@ -257,47 +262,7 @@ paths:
- type: integer
description: The value ``200``.
example: 200
- type: object
title: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: |-
The auth chain. Note that events have a different format depending on
the room version - check the `room version specification`_ for precise
event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "examples/minimal_pdu.json"
state:
type: array
description: |-
The room state. The event format varies depending on the room version -
check the `room version specification`_ for precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "examples/minimal_pdu.json"
required: ["auth_chain", "state", "origin"]
- $ref: "./definitions/send_join_response.yaml"
examples:
application/json: [
200,

136
api/server-server/joins-v2.yaml Normal file
View file

@ -0,0 +1,136 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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.
swagger: '2.0'
info:
title: "Matrix Federation Join Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
# Note: there is no v2 of make_join (yet)
"/send_join/{roomId}/{eventId}":
put:
summary: Submit a signed join event to a resident server
description: |-
.. Note::
This API is nearly identical to the v1 API with the
exception of the response format being fixed.
This endpoint is preferred over the v1 API as it provides
a more standarised response format. Senders which receive
a 400, 404, or other status code which indicates this endpoint
is not available should retry using the v1 API instead.
Submits a signed join event to the resident server for it
to accept it into the room's graph. 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 body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendJoinV2
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be joined.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID for the join event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
schema:
type: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value ``join``.
example: "join"
required: ['membership']
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
example: {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join"
}
}
responses:
200:
description: |-
The full state for the room, having accepted the join event.
schema:
$ref: "./definitions/send_join_response.yaml"
examples:
application/json: {
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
"state": [{"$ref": "examples/minimal_pdu.json"}]
}

2
api/server-server/keys_server.yaml
View file

@ -34,7 +34,7 @@ paths:
Intermediate notary servers should cache a response for half of its
lifetime to avoid serving a stale response. Originating servers should
avoid returning responses that expire in less than an hour to avoid
repeated reqests for a certificate that is about to expire. Requesting
repeated requests for a certificate that is about to expire. Requesting
servers should limit how frequently they query for certificates to
avoid flooding a server with requests.

13
api/server-server/leaving.yaml → api/server-server/leaving-v1.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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.
@ -53,7 +54,7 @@ paths:
200:
description: |-
A template to be used to call ``/send_leave``. Note that
events have a different format depending on the room version - check the
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
required fields for a PDU.**
@ -142,14 +143,18 @@ paths:
put:
summary: Submit a signed leave event to a resident server
description: |-
.. Note::
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
a different format depending on the room version - check
a different format depending on the room version - check
the `room version specification`_ for precise event formats.
**The request and response body here describes the common
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendLeave
operationId: sendLeaveV1
security:
- signedRequest: []
parameters:

140
api/server-server/leaving-v2.yaml Normal file
View file

@ -0,0 +1,140 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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.
swagger: '2.0'
info:
title: "Matrix Federation Leave Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
# Note: there is no v2 of make_leave (yet)
"/send_leave/{roomId}/{eventId}":
put:
summary: Submit a signed leave event to a resident server
description: |-
.. Note::
This API is nearly identical to the v1 API with the
exception of the response format being fixed.
This endpoint is preferred over the v1 API as it provides
a more standarised response format. Senders which receive
a 400, 404, or other status code which indicates this endpoint
is not available should retry using the v1 API instead.
Submits a signed leave event to the resident server for it
to accept it into the room's graph. 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 body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendLeaveV2
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be left.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID for the leave event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
schema:
type: object
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
membership:
type: string
description: The value ``leave``.
example: "leave"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- depth
- content
example: {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
}
}
responses:
200:
description: |-
An empty response to indicate the event was accepted into the graph by
the receiving homeserver.
schema:
type: object
title: Empty Object
description: An empty object.
examples:
application/json: {}

8
api/server-server/third_party_invite.yaml
View file

@ -102,12 +102,16 @@ paths:
properties:
signatures:
type: object
description: The server signatures for this event.
title: Signatures
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string
description: |-
The server signatures for this event.
The signature is calculated using the process
described at `Signing JSON`_.
example: {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"

66
api/server-server/transactions.yaml
View file

@ -38,7 +38,7 @@ paths:
The sending server must wait and retry for a 200 OK response before sending a
transaction with a different ``txnId`` to the receiving server.
Note that events have a different format depending on the room version - check
Note that events have a different format depending on the room version - check
the `room version specification`_ for precise event formats.
operationId: sendTransaction
security:
@ -77,43 +77,33 @@ paths:
The result of processing the transaction. The server is to use this response even in
the event of one or more PDUs failing to be processed.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value ``200``.
example: 200
- type: object
title: PDU Processing Results
description: The results for the processing of each PDU in the transaction.
properties:
pdus:
type: object
description: |-
The PDUs from the original transaction. The string key represents the ID of the
PDU (event) that was processed.
additionalProperties:
type: object
title: PDU Processing Result
description: Information about how the PDU was handled.
properties:
error:
type: string
description: |-
A human readable description about what went wrong in processing this PDU.
If no error is present, the PDU can be considered successfully handled.
example: "You are not allowed to send a message to this room."
required: ['pdus']
type: object
title: PDU Processing Results
description: The results for the processing of each PDU in the transaction.
properties:
pdus:
type: object
description: |-
The PDUs from the original transaction. The string key represents the ID of the
PDU (event) that was processed.
additionalProperties:
type: object
title: PDU Processing Result
description: Information about how the PDU was handled.
properties:
error:
type: string
description: |-
A human readable description about what went wrong in processing this PDU.
If no error is present, the PDU can be considered successfully handled.
example: "You are not allowed to send a message to this room."
required: ['pdus']
examples:
application/json: [
200,
{
"pdus": {
"$successful_event:example.org": {},
"$failed_event:example.org": {
"error": "You are not allowed to send a message to this room."
}
application/json: {
"pdus": {
"$successful_event:example.org": {},
"$failed_event:example.org": {
"error": "You are not allowed to send a message to this room."
}
}
]
}

14
api/server-server/user_keys.yaml
View file

@ -74,7 +74,7 @@ paths:
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.
See the Client-Server Key Algorithms section for more information on
See the `Client-Server Key Algorithms`_ section for more information on
the Key Object format.
additionalProperties:
type: object
@ -89,10 +89,16 @@ paths:
description: The key, encoded using unpadded base64.
signatures:
type: object
description: |-
Signature for the device. Mapped from user ID to signature object.
title: Signatures
additionalProperties:
type: string
type: object
additionalProperties:
type: string
description: |-
Signature of the key object.
The signature is calculated using the process described at `Signing
JSON`_.
required: ['key', 'signatures']
example: {
"@alice:example.com": {