Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-04 21:33:42 +01:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'master' into matthew/msc1779

Browse source
This commit is contained in:
Matthew Hodgson 2019-06-07 19:19:19 +01:00 committed by GitHub
parent be568ba9ab 4b6e2cc956
commit 950415c72a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
173 changed files with 2729 additions and 920 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
.buildkite/pipeline.yaml Normal file
View file

@ -0,0 +1,16 @@
steps:
- label: ":books: Build spec"
command:
- python3 -m venv env
- env/bin/pip install -r scripts/requirements.txt
- ". env/bin/activate; scripts/generate-matrix-org-assets"
artifact_paths:
- assets.tar.gz
plugins:
- docker#v3.0.1:
image: "python:3.6"
- label: "rebuild matrix.org"
trigger: "matrix-dot-org"
async: true
branches: "master"

28
CONTRIBUTING.rst
View file

@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a
server before they can be documented in the specification. This process can take
some time to complete.
For this reason, we have not found the github pull-request model effective for
discussing changes to the specification. Instead, we have adopted the workflow
as described at https://matrix.org/docs/spec/proposals - *please read this for
details on how to contribute spec changes*.
Changes to the protocol (new endpoints, ideas, etc) need to go through the
`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
If you're not sure, visit us at `#matrix-spec:matrix.org`_
and ask.
Other changes
@ -51,8 +52,7 @@ following:
<https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
(If there is any doubt about whether it is the spec or the implementations
that need fixing, please discuss it with us first in `#matrix-dev:matrix.org
<http://matrix.to/#/#matrix-dev:matrix.org>`_.)
that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
* Clarifications to the specification which do not change the behaviour of
Matrix servers or clients in a way which might introduce compatibility
@ -60,14 +60,16 @@ following:
`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
label.
For example, recommendations for UI behaviour do not require a proposal
document. On the other hand, changes to event contents would be best
discussed in a proposal document even though no changes would be necessary to
server implementations.
For example, areas where the specification is unclear do not require a proposal
to fix. On the other hand, introducing new behaviour is best represented by a
proposal.
For such changes, please do just open a `pull request`_.
For such changes, please do just open a `pull request`_. If you're not sure if
your change is covered by the above, please visit `#matrix-spec:matrix.org` and
ask.
.. _pull request: https://help.github.com/articles/about-pull-requests
.. _`pull request`: https://help.github.com/articles/about-pull-requests
.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
Adding to the changelog
@ -96,7 +98,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
* ``breaking`` - Used when the change is not backwards compatible.
* ``deprecation`` - Used when deprecating something
* ``deprecation`` - Used when deprecating something.
All news fragments must have a brief summary explaining the change in the
contents of the file. The summary must end in a full stop to be in line with

2
api/application-service/transactions.yaml
View file

@ -56,7 +56,7 @@ paths:
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member"},
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
{"$ref": "../../event-schemas/examples/m.room.message$m.text"}
]
}
description: Transaction information

27
api/client-server/administrative_contact.yaml
View file

@ -163,6 +163,14 @@ paths:
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the ``id_server`` the identifier was added through. If the
homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``.
example: "example.org"
medium:
type: string
description: The medium of the third party identifier being removed.
@ -180,7 +188,24 @@ paths:
user.
schema:
type: object
properties: {}
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. ``success`` indicates that the
indentity server has unbound the identifier whereas ``no-support``
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: "success"
required:
- id_server_unbind_result
tags:
- User data
"/account/3pid/email/requestToken":

13
api/client-server/content-repo.yaml
View file

@ -41,7 +41,7 @@ paths:
name: Content-Type
type: string
description: The content type of the file being uploaded
x-example: "Content-Type: audio/mpeg"
x-example: "Content-Type: application/pdf"
- in: query
type: string
x-example: "War and Peace.pdf"
@ -51,6 +51,7 @@ paths:
name: "<content>"
description: The content to be uploaded.
required: true
x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
schema:
type: string
example: "<bytes>"
@ -103,7 +104,7 @@ paths:
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
@ -158,7 +159,7 @@ paths:
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
@ -202,6 +203,7 @@ paths:
type: integer
x-example: 64
name: width
required: true
description: |-
The *desired* width of the thumbnail. The actual thumbnail may not
match the size specified.
@ -209,6 +211,7 @@ paths:
type: integer
x-example: 64
name: height
required: true
description: |-
The *desired* height of the thumbnail. The actual thumbnail may not
match the size specified.
@ -226,7 +229,7 @@ paths:
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
@ -328,7 +331,7 @@ paths:
m.upload.size:
type: integer
format: int64
description: |-
description: |-
The maximum size an upload can be in bytes.
Clients SHOULD use this as a guide when uploading content.
If not listed or null, the size limit should be treated as unknown.

12
api/client-server/definitions/push_condition.yaml
View file

@ -16,16 +16,20 @@ title: PushCondition
type: object
properties:
kind:
enum:
- event_match
- contains_display_name
- room_member_count
type: string
description: |-
The kind of condition to apply. See `conditions <#conditions>`_ for
more information on the allowed kinds and how they work.
key:
type: string
description: |-
Required for ``event_match`` conditions. The dot-separated field of the
event to match.
Required for ``sender_notification_permission`` conditions. The field in
the power level event the user needs a minimum power level for. Fields
must be specified under the ``notifications`` property in the power level
event's ``content``.
x-example: content.body
pattern:
type: string

41
api/client-server/definitions/third_party_signed.yaml Normal file
View file

@ -0,0 +1,41 @@
# Copyright 2019 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: Third Party Signed
description: |-
A signature of an ``m.third_party_invite`` token to prove that this user
owns a third party identity which has been invited to the room.
properties:
sender:
type: string
description: The Matrix ID of the user who issued the invite.
example: "@alice:example.org"
mxid:
type: string
description: The Matrix ID of the invitee.
example: "@bob:example.org"
token:
type: string
description: The state key of the m.third_party_invite event.
example: "random8nonce"
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
example: {
"example.org": {
"ed25519:0": "some9signature"
}
}
required: ["sender", "mxid", "token", "signatures"]

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

@ -148,5 +148,14 @@ paths:
}
schema:
type: object
404:
description: There is no mapped room ID for this room alias.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:example.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory

88
api/client-server/event_context.yaml
View file

@ -101,65 +101,35 @@ paths:
- "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
examples:
application/json: {
"end": "t29-57_2_0_2",
"events_after": [
{
"age": 91911336,
"content": {
"body": "7",
"msgtype": "m.text"
},
"event_id": "$14460306086CiUaL:localhost:8480",
"origin_server_ts": 1446030608551,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"type": "m.room.message",
"sender": "@test:localhost:8480"
}
],
"events_before": [
{
"age": 91911903,
"content": {
"body": "5",
"msgtype": "m.text"
},
"event_id": "$14460306074UYTlh:localhost:8480",
"origin_server_ts": 1446030607984,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"type": "m.room.message",
"sender": "@test:localhost:8480"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"age": 3123715284,
"content": {
"creator": "@test:localhost:8480"
},
"event_id": "$14429988040dgQAE:localhost:8480",
"origin_server_ts": 1442998804603,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"state_key": "",
"type": "m.room.create",
"sender": "@test:localhost:8480"
},
{
"age": 2067105053,
"content": {
"avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto",
"displayname": "Bob2",
"membership": "join"
},
"event_id": "$14440554144URDbf:localhost:8480",
"origin_server_ts": 1444055414834,
"replaces_state": "$14440552472PgiGk:localhost:8480",
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"state_key": "@test:localhost:8480",
"type": "m.room.member",
"sender": "@test:localhost:8480"
}
]
"end": "t29-57_2_0_2",
"events_after": [
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
],
"event": {
"event_id": "$f3h4d129462ha:example.com",
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.image"
},
"events_before": [
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.file"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
}
tags:
- Room participation

69
api/client-server/joining.yaml
View file

@ -58,38 +58,9 @@ paths:
name: third_party_signed
schema:
type: object
example: {
"third_party_signed": {
"sender": "@cat:the.hat",
"mxid": "@green:eggs.ham",
"token": "random8nonce",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
}
}
}
properties:
third_party_signed:
type: object
title: ThirdPartySigned
description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
properties:
sender:
type: string
description: The Matrix ID of the user who issued the invite.
mxid:
type: string
description: The Matrix ID of the invitee.
token:
type: string
description: The state key of the m.third_party_invite event.
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
required: ["sender", "mxid", "token", "signatures"]
$ref: "definitions/third_party_signed.yaml"
responses:
200:
description: |-
@ -163,45 +134,9 @@ paths:
name: third_party_signed
schema:
type: object
example: {
"third_party_signed": {
"signed": {
"sender": "@cat:the.hat",
"mxid": "@green:eggs.ham",
"token": "random8nonce",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
}
}
}
}
properties:
third_party_signed:
type: object
title: ThirdPartySigned
description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
properties:
signed:
type: object
title: Signed
properties:
sender:
type: string
description: The Matrix ID of the user who issued the invite.
mxid:
type: string
description: The Matrix ID of the invitee.
token:
type: string
description: The state key of the m.third_party_invite event.
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
required: ["sender", "mxid", "token", "signatures"]
required: ["signed"]
$ref: "definitions/third_party_signed.yaml"
responses:
200:
description: |-

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

@ -253,7 +253,7 @@ paths:
responses:
200:
description:
The claimed keys
The claimed keys.
schema:
type: object
properties:

7
api/client-server/logout.yaml
View file

@ -32,7 +32,8 @@ paths:
summary: Invalidates a user access token
description: |-
Invalidates an existing access token, so that it can no longer be used for
authorization.
authorization. The device associated with the access token is also deleted.
`Device keys <#device-keys>`_ for the device are deleted alongside the device.
operationId: logout
security:
- accessToken: []
@ -49,7 +50,9 @@ paths:
summary: Invalidates all access tokens for a user
description: |-
Invalidates all access tokens for a user, so that they can no longer be used for
authorization. This includes the access token that made this request.
authorization. This includes the access token that made this request. All devices
for the user are also deleted. `Device keys <#device-keys>`_ for the device are
deleted alongside the device.
This endpoint does not require UI authorization because UI authorization is
designed to protect against attacks where the someone gets hold of a single access

44
api/client-server/message_pagination.yaml
View file

@ -103,7 +103,10 @@ paths:
chunk:
type: array
description: |-
A list of room events.
A list of room events. The order depends on the ``dir`` parameter.
For ``dir=b`` events will be in reverse-chronological order,
for ``dir=f`` in chronological order, so that events start
at the ``from`` point.
items:
type: object
title: RoomEvent
@ -114,43 +117,16 @@ paths:
"end": "t47409-4357353_219380_26003_2265",
"chunk": [
{
"origin_server_ts": 1444812213737,
"sender": "@alice:example.com",
"event_id": "$1444812213350496Caaaa:example.com",
"content": {
"body": "hello world",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 1042
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"origin_server_ts": 1444812194656 ,
"sender": "@bob:example.com",
"event_id": "$1444812213350496Cbbbb:example.com",
"content": {
"body": "the world is big",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 20123
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.name"
},
{
"origin_server_ts": 1444812163990,
"sender": "@bob:example.com",
"event_id": "$1444812213350496Ccccc:example.com",
"content": {
"name": "New room name"
},
"prev_content": {
"name": "Old room name"
},
"state_key": "",
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.name",
"age": 50789
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
]
}

11
api/client-server/notifications.yaml
View file

@ -75,16 +75,7 @@ paths:
"room_id": "!abcdefg:example.com",
"ts": 1475508881945,
"event": {
"sender": "@alice:example.com",
"type": "m.room.message",
"age": 124524,
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
}
]

136
api/client-server/old_sync.yaml
View file

@ -64,18 +64,7 @@ paths:
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
}
{"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
]
}
schema:
@ -142,16 +131,7 @@ paths:
application/json: {
"end": "s3456_9_0",
"presence": [
{
"content": {
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"last_active_ago": 31053,
"presence": "online",
"user_id": "@bob:localhost"
},
"type": "m.presence"
}
{"$ref": "definitions/event-schemas/examples/m.presence"}
],
"account_data": [
{
@ -167,28 +147,12 @@ paths:
"messages": {
"chunk": [
{
"age": 343513403,
"content": {
"body": "foo",
"msgtype": "m.text"
},
"event_id": "$14328044851tzTJS:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:localhost",
"origin_server_ts": 1432804487480,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
],
"end": "s3456_9_0",
@ -197,81 +161,20 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state": [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:localhost",
"origin_server_ts": 1425999732392,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:localhost",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@alice:localhost",
"type": "m.room.member",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:localhost"
},
"event_id": "$14259997320KhbwJ:localhost",
"origin_server_ts": 1425999732089,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:localhost",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:localhost",
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@bob:localhost",
"type": "m.room.member",
"sender": "@bob:localhost"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:localhost": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:localhost",
"origin_server_ts": 1425999732285,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
],
"visibility": "private",
@ -423,16 +326,7 @@ paths:
200:
description: The full event.
examples:
application/json: {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
}
application/json: {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
schema:
allOf:
- "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"

12
api/client-server/peeking_events.yaml
View file

@ -75,16 +75,8 @@ paths:
"end": "s3457_9_0",
"chunk": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
"room_id": "!somewhere:over.the.rainbow",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
]
}

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

@ -29,7 +29,8 @@ paths:
post:
summary: Register for an account on this homeserver.
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
This API endpoint uses the `User-Interactive Authentication API`_, except in
the cases where a guest account is being registered.
Register for an account on this homeserver.
@ -59,6 +60,11 @@ paths:
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
When registering a guest account, all parameters in the request body
with the exception of ``initial_device_display_name`` MUST BE ignored
by the server. The server MUST pick a ``device_id`` for the account
regardless of input.
operationId: register
parameters:
- in: query
@ -72,7 +78,7 @@ paths:
enum:
- guest
- user
description: The kind of account to register. Defaults to `user`.
description: The kind of account to register. Defaults to ``user``.
- in: body
name: body
schema:
@ -80,13 +86,11 @@ paths:
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself. It should be
left empty, or omitted, unless an earlier call returned an
response with status code 401.
Additional authentication information for the
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself.
"$ref": "definitions/auth_data.yaml"
bind_email:
type: boolean
@ -94,6 +98,12 @@ paths:
If true, the server binds the email used for authentication to
the Matrix ID with the identity server.
example: false
bind_msisdn:
type: boolean
description: |-
If true, the server binds the phone number used for authentication
to the Matrix ID with the identity server.
example: false
username:
type: string
description: |-
@ -194,6 +204,18 @@ paths:
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
403:
description: |-
The homeserver does not permit registering the account. This response
can be used to identify that a particular ``kind`` of account is not
allowed, or that registration is generally not supported by the homeserver.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Registration is disabled"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -326,13 +348,17 @@ paths:
description: |-
Changes the password for an account on this homeserver.
This API endpoint uses the `User-Interactive Authentication API`_.
This API endpoint uses the `User-Interactive Authentication API`_ to
ensure the user changing the password is actually the owner of the
account.
An access token should be submitted to this endpoint if the client has
an active session.
The homeserver may change the flows available depending on whether a
valid access token is provided.
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.
security:
- accessToken: []
operationId: changePassword
@ -520,13 +546,39 @@ paths:
description: |-
Additional authentication information for the user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
id_server:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the ``id_server``
that was originally use to bind each identifier. If the
homeserver does not know which ``id_server`` that was,
it must return an ``id_server_unbind_result`` of
``no-support``.
example: "example.org"
responses:
200:
description: The account has been deactivated.
examples:
application/json: {}
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- "success"
- "no-support"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the user's 3PIDs from the identity server(s). ``success`` indicates
that all identifiers have been unbound from the identity server while
``no-support`` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
being unable to determine an identity server to unbind from. This
must be ``success`` if the homeserver has no identifiers to unbind
for the user.
example: "success"
required:
- id_server_unbind_result
401:
description: |-
The homeserver requires additional authentication information.

89
api/client-server/room_initial_sync.yaml
View file

@ -43,28 +43,12 @@ paths:
"messages": {
"chunk": [
{
"age": 343513403,
"content": {
"body": "foo",
"msgtype": "m.text"
},
"event_id": "$14328044851tzTJS:example.com",
"origin_server_ts": 1432804485886,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:example.com",
"origin_server_ts": 1432804487480,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"sender": "@bob:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.file"
}
],
"end": "s3456_9_0",
@ -73,81 +57,20 @@ paths:
"room_id": "!636q39766251:example.com",
"state": [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:example.com",
"origin_server_ts": 1425999732392,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:example.com": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:example.com",
"origin_server_ts": 1425999732285,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
],
"visibility": "private",

136
api/client-server/rooms.yaml
View file

@ -42,7 +42,7 @@ paths:
name: roomId
description: The ID of the room the event is in.
required: true
x-example: "!asfDuShaf7Gafaw:matrix.org"
x-example: "!636q39766251:matrix.org"
- in: path
type: string
name: eventId
@ -54,15 +54,9 @@ paths:
description: The full event.
examples:
application/json: {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
}
"room_id": "!636q39766251:matrix.org",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
schema:
allOf:
- "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
@ -178,84 +172,23 @@ paths:
description: The current state of the room
examples:
application/json: [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:example.com",
"origin_server_ts": 1425999732392,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:example.com"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:example.com"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:example.com": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:example.com",
"origin_server_ts": 1425999732285,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:example.com"
}
]
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
]
schema:
type: array
title: RoomState
@ -300,33 +233,8 @@ paths:
application/json: {
"chunk": [
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
}

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

@ -280,7 +280,7 @@ paths:
Any groups that were requested.
The outer ``string`` key is the group key requested (eg: ``room_id``
or ``sender``). The inner ``string`` key is the grouped value (eg:
or ``sender``). The inner ``string`` key is the grouped value (eg:
a room's ID or a user's ID).
additionalProperties:
type: object
@ -347,16 +347,9 @@ paths:
{
"rank": 0.00424866,
"result": {
"age": 526228296,
"content": {
"body": "Test content martians and men",
"msgtype": "m.text"
},
"event_id": "$144429830826TWwbB:localhost",
"origin_server_ts": 1444298308034,
"room_id": "!qPewotXpIctQySfjSy:localhost",
"type": "m.room.message",
"sender": "@test:localhost"
"event_id": "$144429830826TWwbB:localhost",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
}
]

69
api/client-server/sync.yaml
View file

@ -212,30 +212,7 @@ paths:
events:
description: The StrippedState events that form the invite state.
items:
description: |-
A stripped down state event, with only the ``type``, ``state_key``,
``sender``, and ``content`` keys.
properties:
content:
description: The ``content`` for the event.
title: EventContent
type: object
state_key:
description: The ``state_key`` for the event.
type: string
type:
description: The ``type`` for the event.
type: string
sender:
description: The ``sender`` for the event.
type: string
required:
- type
- state_key
- content
- sender
title: StrippedState
type: object
$ref: "definitions/event-schemas/schema/stripped_state.yaml"
type: array
leave:
title: Left rooms
@ -310,11 +287,7 @@ paths:
"next_batch": "s72595_4483_1934",
"presence": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.presence",
"content": {"presence": "online"}
}
{"$ref": "definitions/event-schemas/examples/m.presence"}
]
},
"account_data": {
@ -333,36 +306,20 @@ paths:
"state": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@alice:example.com",
"content": {"membership": "join"},
"origin_server_ts": 1417731086795,
"event_id": "$66697273743031:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
},
"timeline": {
"events": [
{
"sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "join"},
"prev_content": {"membership": "invite"},
"origin_server_ts": 1417731086795,
"event_id": "$7365636s6r6432:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"sender": "@alice:example.com",
"type": "m.room.message",
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
],
"limited": true,
@ -370,18 +327,12 @@ paths:
},
"ephemeral": {
"events": [
{
"type": "m.typing",
"content": {"user_ids": ["@alice:example.com"]}
}
{"$ref": "definitions/event-schemas/examples/m.typing"}
]
},
"account_data": {
"events": [
{
"type": "m.tag",
"content": {"tags": {"work": {"order": 1}}}
},
{"$ref": "definitions/event-schemas/examples/m.tag"},
{
"type": "org.example.custom.room.config",
"content": {

85
api/identity/associations.yaml
View file

@ -90,7 +90,7 @@ paths:
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/bind":
"/3pid/bind":
post:
summary: Publish an association between a session and a Matrix user ID.
description: |-
@ -201,3 +201,86 @@ paths:
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/unbind":
post:
summary: Remove an association between a session and a Matrix user ID.
description: |-
Remove an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session's 3pids will not
return the removed association.
The identity server should authenticate the request in one of two
ways:
1. The request is signed by the homeserver which controls the ``user_id``.
2. The request includes the ``sid`` and ``client_secret`` parameters,
as per ``/3pid/bind``, which proves ownership of the 3PID.
If this endpoint returns a JSON Matrix error, that error should be passed
through to the client requesting an unbind through a homeserver, if the
homeserver is acting on behalf of a client.
operationId: unbind
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:example.org",
"threepid": {
"medium": "email",
"address": "monkeys_have_ears@example.org"
}
}
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
threepid:
type: object
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using ``sid`` and ``client_secret`` to authenticate this request.
properties:
medium:
type: string
description: |-
A medium from the `3PID Types`_ Appendix, matching the medium
of the identifier to unbind.
address:
type: string
description: The 3PID address to remove.
required: ['medium', 'address']
required: ["threepid", "mxid"]
responses:
200:
description: The association was successfully removed.
examples:
application/json: {}
schema:
type: object
400:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
404:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
501:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.

3
api/identity/definitions/request_email_validation.yaml
View file

@ -39,7 +39,8 @@ properties:
avoid repeatedly sending the same email in the case of request
retries between the POSTing user and the identity server.
The client should increment this value if they desire a new
email (e.g. a reminder) to be sent.
email (e.g. a reminder) to be sent. If they do not, the server
should respond with success but not resend the email.
example: 1
next_link:
type: string

47
api/identity/store_invite.yaml
View file

@ -50,31 +50,66 @@ paths:
requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
Currently, invites may only be issued for 3pids of the ``email`` medium.
Optional fields in the request should be populated to the best of the
server's ability. Identity servers may use these variables when notifying
the ``address`` of the pending invite for display purposes.
operationId: storeInvite
parameters:
- in: body
name: body
schema:
type: object
example: {
"medium": "email",
"address": "foo@bar.baz",
"room_id": "!something:example.tld",
"sender": "@bob:example.com"
}
properties:
medium:
type: string
description: The literal string ``email``.
example: "email"
address:
type: string
description: The email address of the invited user.
example: "foo@example.com"
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the ``m.room.canonical_alias``
state event.
example: "#somewhere:exmaple.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the ``m.room.avatar`` state event.
example: "mxc://example.org/s0meM3dia"
room_join_rules:
type: string
description: |-
The ``join_rule`` for the room to which the user is invited. This should
be retrieved from the ``m.room.join_rules`` state event.
example: "public"
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the ``m.room.name`` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
example: "Bob Smith"
sender_avatar_url:
type: string
description: The Content URI for the avatar of the user ID initiating the invite.
example: "mxc://example.org/an0th3rM3dia"
required: ["medium", "address", "room_id", "sender"]
responses:
200:

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

@ -64,7 +64,7 @@ paths:
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
schema:
$ref: "definitions/transaction.yaml"
$ref: "definitions/unlimited_pdu_transaction.yaml"
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing

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

@ -20,6 +20,10 @@ allOf:
- $ref: "unsigned_pdu_base.yaml"
- type: object
properties:
redacts:
type: string
description: For redaction events, the ID of the event being redacted.
example: "$def/456+oldevent"
auth_events:
type: array
items:

47
api/server-server/definitions/pdu_v4.yaml Normal file
View file

@ -0,0 +1,47 @@
# Copyright 2019 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: Persistent Data Unit
description: A persistent data unit (event) for room version 4 and beyond.
example:
$ref: "../examples/pdu_v4.json"
allOf:
- $ref: "pdu_v3.yaml"
- type: object
properties:
redacts:
type: string
description: For redaction events, the ID of the event being redacted.
example: "$def_456-oldevent"
auth_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the authorization events that would
allow this event to be in the room.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
prev_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the most recent events in the room
that the homeserver was aware of when it made this event.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
required:
- auth_events
- prev_events

32
api/server-server/definitions/single_pdu_transaction.yaml Normal file
View file

@ -0,0 +1,32 @@
# Copyright 2019 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
allOf:
- $ref: "transaction.yaml"
properties:
pdus:
type: array
description: |-
A single PDU. 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>`_ contained in the transaction. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
properties: []
example:
$ref: "../examples/minimal_pdu.json"
required: ['origin', 'origin_server_ts', 'pdus']

33
api/server-server/definitions/unlimited_pdu_transaction.yaml Normal file
View file

@ -0,0 +1,33 @@
# Copyright 2019 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
allOf:
- $ref: "transaction.yaml"
properties:
pdus:
type: array
description: |-
List of persistent updates to rooms. 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>`_ contained in the transaction. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
properties: []
example:
$ref: "../examples/minimal_pdu.json"
required: ['origin', 'origin_server_ts', 'pdus']

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

@ -156,4 +156,4 @@ paths:
200:
description: A transaction containing a single PDU which is the event requested.
schema:
$ref: "definitions/transaction.yaml"
$ref: "definitions/single_pdu_transaction.yaml"

3
api/server-server/examples/pdu_v3.json
View file

@ -15,5 +15,6 @@
"prev_events": [
"$base64encodedeventid",
"$adifferenteventid"
]
],
"redacts": "$some/old+event"
}

12
api/server-server/examples/pdu_v4.json Normal file
View file

@ -0,0 +1,12 @@
{
"$ref": "pdu_v3.json",
"auth_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
],
"prev_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
],
"redacts": "$some-old_event"
}

73
api/server-server/invites-v1.yaml
View file

@ -82,35 +82,9 @@ paths:
identify the room. The recommended events to include are the join rules,
canonical alias, avatar, and name of the room.
items:
type: object
title: Invite Room State Event
properties:
type:
type: string
description: The type of event.
example: "m.room.join_rules"
state_key:
type: string
description: The state key for the event. May be an empty string.
example: ""
content:
type: object
description: The content for the event.
sender:
type: string
description: The sender of the event.
example: "@someone:matrix.org"
required: ['type', 'state_key', 'content', 'sender']
example: [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
}
]
$ref: "../../event-schemas/schema/stripped_state.yaml"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
example: {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
@ -118,26 +92,6 @@ paths:
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
},
"content": {
"membership": "invite"
},
@ -180,24 +134,9 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
"invite_room_state": {
"$ref": "../../../event-schemas/examples/invite_room_state.json"
}
},
"content": {
"membership": "invite"

73
api/server-server/invites-v2.yaml
View file

@ -83,35 +83,9 @@ paths:
identify the room. The recommended events to include are the join rules,
canonical alias, avatar, and name of the room.
items:
type: object
title: Invite Room State Event
properties:
type:
type: string
description: The type of event.
example: "m.room.join_rules"
state_key:
type: string
description: The state key for the event. May be an empty string.
example: ""
content:
type: object
description: The content for the event.
sender:
type: string
description: The sender of the event.
example: "@someone:matrix.org"
required: ['type', 'state_key', 'content', 'sender']
example: [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
}
]
$ref: "../../event-schemas/schema/stripped_state.yaml"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
required: ['room_version', 'event']
example: {
"room_version": "2",
@ -130,25 +104,7 @@ paths:
"ed25519:key_version": "SomeSignatureHere"
},
}
},
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
}
}
responses:
200:
@ -174,24 +130,9 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
"invite_room_state": {
"$ref": "../../../event-schemas/examples/invite_room_state.json"
}
},
"content": {
"membership": "invite"

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

@ -63,7 +63,7 @@ paths:
- one_time_keys
responses:
200:
description: The claimed keys
description: The claimed keys.
schema:
type: object
properties:

1
changelogs/application_service/newsfragments/1650.clarification Normal file
View file

@ -0,0 +1 @@
Change examples to use example.org instead of a real domain.

1
changelogs/application_service/newsfragments/2037.clarification Normal file
View file

@ -0,0 +1 @@
Add missing definition for how appservices verify requests came from a homeserver.

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

@ -0,0 +1 @@
Change examples to use example.org instead of a real domain.

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

@ -0,0 +1 @@
Clarify that ``state_default`` in ``m.room.power_levels`` always defaults to 50.

2
changelogs/client_server/newsfragments/1701.feature
View file

@ -1 +1 @@
Documented megolm session export format.
Add megolm session export format.

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

@ -1 +1 @@
Add missing status_msg to m.presence schema.
Add missing ``status_msg`` to ``m.presence`` schema.

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

@ -1 +1 @@
Add the missing `m.push_rules` event schema.
Add the missing ``m.push_rules`` event schema.

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

@ -0,0 +1 @@
Clarify how modern day local echo is meant to be solved by clients.

0
changelogs/client_server/newsfragments/1903.feature → changelogs/client_server/newsfragments/1908.feature
View file

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

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

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

@ -0,0 +1 @@
Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``.

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

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

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

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

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

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

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

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

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

@ -0,0 +1 @@
Clarify how ``m.login.dummy`` can be used to disambiguate login flows.

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

@ -0,0 +1 @@
Remove ``prev_content`` from the redaction algorithm's essential keys list.

1
changelogs/client_server/newsfragments/2020.feature Normal file
View file

@ -0,0 +1 @@
Add a ``.m.rule.tombstone`` default push rule for room ugprade notifications.

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

@ -0,0 +1 @@
Fix the ``third_party_signed`` definitions for the join APIs.

1
changelogs/client_server/newsfragments/2026.feature Normal file
View file

@ -0,0 +1 @@
Add support for sending server notices to clients.

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

@ -0,0 +1 @@
Clarify why User Interactive Auth is used on password changes and how access tokens are handled.

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

@ -0,0 +1 @@
Clarify that devices are deleted upon logout.

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

@ -0,0 +1 @@
Add ``M_NOT_FOUND`` error definition for deleting room aliases.

1
changelogs/client_server/newsfragments/2030.feature Normal file
View file

@ -0,0 +1 @@
Add MSISDN (phone number) support to User-Interactive Authentication.

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

@ -0,0 +1 @@
Add missing ``reason`` to ``m.call.hangup``.

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

@ -0,0 +1 @@
Clarify how redactions affect room state.

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

@ -0,0 +1 @@
Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers.

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

@ -0,0 +1 @@
Fix example ``Content-Type`` for ``/media/upload`` request.

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

@ -0,0 +1 @@
Clarify that login flows are meant to be completed in order.

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

@ -0,0 +1 @@
Clarify that clients should not send read receipts for their own messages.

1
changelogs/client_server/newsfragments/2046.feature Normal file
View file

@ -0,0 +1 @@
Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server.

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

@ -0,0 +1 @@
Use consistent examples of events throughout the specification.

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

@ -0,0 +1 @@
Clarify which push rule condition kinds exist.

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

@ -0,0 +1 @@
Clarify the required fields on ``m.file`` (and similar) messages.

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

@ -0,0 +1 @@
Clarify that User-Interactive Authentication stages cannot be attempted more than once.

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

@ -0,0 +1 @@
Clarify which parameters apply in what scenarios on ``/register``.

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

@ -0,0 +1 @@
Clarify how to interpret changes of ``membership`` over time.

1
changelogs/client_server/newsfragments/2059.feature Normal file
View file

@ -0,0 +1 @@
Add support for Olm sessions becoming un-stuck.

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

@ -0,0 +1 @@
Clarify exactly what invite_room_state consists of.

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

@ -0,0 +1 @@
Clarify the order events in chunk are returned in for ``/messages``.

1
changelogs/client_server/newsfragments/2072.feature Normal file
View file

@ -0,0 +1 @@
Add interactive device verification, including a common framework for device verification.

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

@ -0,0 +1 @@
Clarify when authorization and rate-limiting are not applicable.

1
changelogs/identity_service/newsfragments/1967.clarification Normal file
View file

@ -0,0 +1 @@
Fix route for ``/3pid/bind``.

1
changelogs/identity_service/newsfragments/2046.new Normal file
View file

@ -0,0 +1 @@
Add ``/3pid/unbind`` for removing 3PIDs.

1
changelogs/identity_service/newsfragments/2049.clarification Normal file
View file

@ -0,0 +1 @@
Add missing aesthetic parameters to ``/store-invite``.

1
changelogs/identity_service/newsfragments/2057.clarification Normal file
View file

@ -0,0 +1 @@
Clarify what the client should receive upon sending an identical email validation request multiple times.

1
changelogs/identity_service/newsfragments/2086.clarification Normal file
View file

@ -0,0 +1 @@
Clarify that the default transport is JSON over HTTP.

1
changelogs/server_server/newsfragments/1650.clarification Normal file
View file

@ -0,0 +1 @@
Change examples to use example.org instead of a real domain.

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

@ -1 +0,0 @@
Fix the `access_token` parameter in the open_id endpoint.

1
changelogs/server_server/newsfragments/1906.clarification Normal file
View file

@ -0,0 +1 @@
Fix the ``access_token`` parameter in the open_id endpoint.

1
changelogs/server_server/newsfragments/1991.clarification Normal file
View file

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

1
changelogs/server_server/newsfragments/2067.clarification Normal file
View file

@ -0,0 +1 @@
Clarify exactly what invite_room_state consists of.

1
changelogs/server_server/newsfragments/2081.clarification Normal file
View file

@ -0,0 +1 @@
Clarify which servers are supposed to sign events.

1
changelogs/server_server/newsfragments/2095.clarification Normal file
View file

@ -0,0 +1 @@
Clarify how many PDUs are contained in transaction objects for various endpoints.

66
data-definitions/sas-emoji.json Normal file
View file

@ -0,0 +1,66 @@
[
{"number": 0, "emoji": "🐶", "description": "Dog", "unicode": "U+1F436"},
{"number": 1, "emoji": "🐱", "description": "Cat", "unicode": "U+1F431"},
{"number": 2, "emoji": "🦁", "description": "Lion", "unicode": "U+1F981"},
{"number": 3, "emoji": "🐎", "description": "Horse", "unicode": "U+1F40E"},
{"number": 4, "emoji": "🦄", "description": "Unicorn", "unicode": "U+1F984"},
{"number": 5, "emoji": "🐷", "description": "Pig", "unicode": "U+1F437"},
{"number": 6, "emoji": "🐘", "description": "Elephant", "unicode": "U+1F418"},
{"number": 7, "emoji": "🐰", "description": "Rabbit", "unicode": "U+1F430"},
{"number": 8, "emoji": "🐼", "description": "Panda", "unicode": "U+1F43C"},
{"number": 9, "emoji": "🐓", "description": "Rooster", "unicode": "U+1F413"},
{"number": 10, "emoji": "🐧", "description": "Penguin", "unicode": "U+1F427"},
{"number": 11, "emoji": "🐢", "description": "Turtle", "unicode": "U+1F422"},
{"number": 12, "emoji": "🐟", "description": "Fish", "unicode": "U+1F41F"},
{"number": 13, "emoji": "🐙", "description": "Octopus", "unicode": "U+1F419"},
{"number": 14, "emoji": "🦋", "description": "Butterfly", "unicode": "U+1F98B"},
{"number": 15, "emoji": "🌷", "description": "Flower", "unicode": "U+1F337"},
{"number": 16, "emoji": "🌳", "description": "Tree", "unicode": "U+1F333"},
{"number": 17, "emoji": "🌵", "description": "Cactus", "unicode": "U+1F335"},
{"number": 18, "emoji": "🍄", "description": "Mushroom", "unicode": "U+1F344"},
{"number": 19, "emoji": "🌏", "description": "Globe", "unicode": "U+1F30F"},
{"number": 20, "emoji": "🌙", "description": "Moon", "unicode": "U+1F319"},
{"number": 21, "emoji": "☁️", "description": "Cloud", "unicode": "U+2601U+FE0F"},
{"number": 22, "emoji": "🔥", "description": "Fire", "unicode": "U+1F525"},
{"number": 23, "emoji": "🍌", "description": "Banana", "unicode": "U+1F34C"},
{"number": 24, "emoji": "🍎", "description": "Apple", "unicode": "U+1F34E"},
{"number": 25, "emoji": "🍓", "description": "Strawberry", "unicode": "U+1F353"},
{"number": 26, "emoji": "🌽", "description": "Corn", "unicode": "U+1F33D"},
{"number": 27, "emoji": "🍕", "description": "Pizza", "unicode": "U+1F355"},
{"number": 28, "emoji": "🎂", "description": "Cake", "unicode": "U+1F382"},
{"number": 29, "emoji": "❤️", "description": "Heart", "unicode": "U+2764U+FE0F"},
{"number": 30, "emoji": "😀", "description": "Smiley", "unicode": "U+1F600"},
{"number": 31, "emoji": "🤖", "description": "Robot", "unicode": "U+1F916"},
{"number": 32, "emoji": "🎩", "description": "Hat", "unicode": "U+1F3A9"},
{"number": 33, "emoji": "👓", "description": "Glasses", "unicode": "U+1F453"},
{"number": 34, "emoji": "🔧", "description": "Spanner", "unicode": "U+1F527"},
{"number": 35, "emoji": "🎅", "description": "Santa", "unicode": "U+1F385"},
{"number": 36, "emoji": "👍", "description": "Thumbs Up", "unicode": "U+1F44D"},
{"number": 37, "emoji": "☂️", "description": "Umbrella", "unicode": "U+2602U+FE0F"},
{"number": 38, "emoji": "⌛", "description": "Hourglass", "unicode": "U+231B"},
{"number": 39, "emoji": "⏰", "description": "Clock", "unicode": "U+23F0"},
{"number": 40, "emoji": "🎁", "description": "Gift", "unicode": "U+1F381"},
{"number": 41, "emoji": "💡", "description": "Light Bulb", "unicode": "U+1F4A1"},
{"number": 42, "emoji": "📕", "description": "Book", "unicode": "U+1F4D5"},
{"number": 43, "emoji": "✏️", "description": "Pencil", "unicode": "U+270FU+FE0F"},
{"number": 44, "emoji": "📎", "description": "Paperclip", "unicode": "U+1F4CE"},
{"number": 45, "emoji": "✂️", "description": "Scissors", "unicode": "U+2702U+FE0F"},
{"number": 46, "emoji": "🔒", "description": "Lock", "unicode": "U+1F512"},
{"number": 47, "emoji": "🔑", "description": "Key", "unicode": "U+1F511"},
{"number": 48, "emoji": "🔨", "description": "Hammer", "unicode": "U+1F528"},
{"number": 49, "emoji": "☎️", "description": "Telephone", "unicode": "U+260EU+FE0F"},
{"number": 50, "emoji": "🏁", "description": "Flag", "unicode": "U+1F3C1"},
{"number": 51, "emoji": "🚂", "description": "Train", "unicode": "U+1F682"},
{"number": 52, "emoji": "🚲", "description": "Bicycle", "unicode": "U+1F6B2"},
{"number": 53, "emoji": "✈️", "description": "Aeroplane", "unicode": "U+2708U+FE0F"},
{"number": 54, "emoji": "🚀", "description": "Rocket", "unicode": "U+1F680"},
{"number": 55, "emoji": "🏆", "description": "Trophy", "unicode": "U+1F3C6"},
{"number": 56, "emoji": "⚽", "description": "Ball", "unicode": "U+26BD"},
{"number": 57, "emoji": "🎸", "description": "Guitar", "unicode": "U+1F3B8"},
{"number": 58, "emoji": "🎺", "description": "Trumpet", "unicode": "U+1F3BA"},
{"number": 59, "emoji": "🔔", "description": "Bell", "unicode": "U+1F514"},
{"number": 60, "emoji": "⚓", "description": "Anchor", "unicode": "U+2693"},
{"number": 61, "emoji": "🎧", "description": "Headphones", "unicode": "U+1F3A7"},
{"number": 62, "emoji": "📁", "description": "Folder", "unicode": "U+1F4C1"},
{"number": 63, "emoji": "📌", "description": "Pin", "unicode": "U+1F4CC"}
]

7
event-schemas/check_examples.py
View file

@ -106,14 +106,17 @@ def check_example_dir(exampledir, schemadir):
if filename.startswith("."):
# Skip over any vim .swp files.
continue
if filename.endswith(".json"):
# Skip over any explicit examples (partial event definitions)
continue
cwd = os.path.basename(os.path.dirname(os.path.join(root, filename)))
if cwd == "core":
# Skip checking the underlying definitions
continue
examplepath = os.path.join(root, filename)
schemapath = examplepath.replace(exampledir, schemadir)
if schemapath.find("#") >= 0:
schemapath = schemapath[:schemapath.find("#")]
if schemapath.find("$") >= 0:
schemapath = schemapath[:schemapath.find("$")]
try:
check_example_file(examplepath, schemapath)
except Exception as e:

18
event-schemas/examples/invite_room_state.json Normal file
View file

@ -0,0 +1,18 @@
[
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]

4
event-schemas/examples/m.dummy Normal file
View file

@ -0,0 +1,4 @@
{
"content": {},
"type": "m.dummy"
}

12
event-schemas/examples/m.key.verification.accept Normal file
View file

@ -0,0 +1,12 @@
{
"type": "m.key.verification.accept",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1",
"key_agreement_protocol": "curve25519",
"hash": "sha256",
"message_authentication_code": "hkdf-hmac-sha256",
"short_authentication_string": ["decimal", "emoji"],
"commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}

8
event-schemas/examples/m.key.verification.cancel Normal file
View file

@ -0,0 +1,8 @@
{
"type": "m.key.verification.cancel",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"code": "m.user",
"reason": "User rejected the key verification request"
}
}

7
event-schemas/examples/m.key.verification.key Normal file
View file

@ -0,0 +1,7 @@
{
"type": "m.key.verification.key",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}

10
event-schemas/examples/m.key.verification.mac Normal file
View file

@ -0,0 +1,10 @@
{
"type": "m.key.verification.mac",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA",
"mac": {
"ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}

11
event-schemas/examples/m.key.verification.request Normal file
View file

@ -0,0 +1,11 @@
{
"type": "m.key.verification.request",
"content": {
"from_device": "AliceDevice2",
"transaction_id": "S0meUniqueAndOpaqueString",
"methods": [
"m.sas.v1"
],
"timestamp": 1559598944869
}
}

8
event-schemas/examples/m.key.verification.start Normal file
View file

@ -0,0 +1,8 @@
{
"type": "m.key.verification.start",
"content": {
"from_device": "BobDevice1",
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1"
}
}

12
event-schemas/examples/m.key.verification.start$m.sas.v1 Normal file
View file

@ -0,0 +1,12 @@
{
"type": "m.key.verification.start",
"content": {
"from_device": "BobDevice1",
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1",
"key_agreement_protocols": ["curve25519"],
"hashes": ["sha256"],
"message_authentication_codes": ["hkdf-hmac-sha256"],
"short_authentication_string": ["decimal", "emoji"]
}
}

Some files were not shown because too many files have changed in this diff Show more