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

Move raw API and event schemas into /data directory

Browse source 
Historical note: this was originally a series of several commits, spread out
over several weeks. They have been squashed together to make `git annotate`
work properly.

The original commits were:
 * 91ab3934 <Will> 2021-01-25 21:16:42 -0800 Add raw API end event schemas into /data directory
 * aae22f47 <Will> 2021-01-25 21:33:06 -0800 Remove non-data files
 * 1092d4ca <Will> 2021-01-26 20:41:33 -0800 Add data-compatiuble extension (.yaml) to all data files that currently omit one
 * 21060109 <Will> 2021-01-26 20:57:28 -0800 Remove symlink to event-schemas, and update openAPI schema paths accordingly
 * 4f633845 <Travis Ralston> 2021-04-12 21:54:54 -0600 Fix event schema examples too
 * 301c7b2f <Will> 2021-02-05 10:15:42 -0800 Restore docs describing OpenAPI extensions that we use
This commit is contained in:
Will 2021-01-25 21:16:42 -08:00 • committed by Richard van der Hoff
parent a26c352d78
commit 00c6a866e2
327 changed files with 82 additions and 10822 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -0,0 +1,91 @@
# 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: m.device_list_update
description: |-
An EDU that lets servers push details to each other when one of their users
adds a new device to their account, required for E2E encryption to correctly
target the current set of devices for a given user. This event will also be
sent when an existing device gets a new cross-signing signature.
# FIXME: It's very unclear why we have this API surface for synchronising
# device lists, rather than just using a room (which could also be used for
# profile info, etc). But documenting what we have for now...
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.device_list_update']
description: The string ``m.device_list_update``.
example: "m.device_list_update"
content:
type: object
description: The description of the device whose details has changed.
title: Device List Update
properties:
user_id:
type: string
description: The user ID who owns this device.
example: "@john:example.com"
device_id:
type: string
description: The ID of the device whose details are changing.
example: "QBUAZIFURK"
device_display_name:
type: string
description: |-
The public human-readable name of this device. Will be absent
if the device has no name.
example: "Mobile"
stream_id:
type: integer
description: |-
An ID sent by the server for this update, unique for a given
user_id. Used to identify any gaps in the sequence of ``m.device_list_update``
EDUs broadcast by a server.
example: 6
prev_id:
type: array
description: |-
The stream_ids of any prior m.device_list_update EDUs sent for this user
which have not been referred to already in an EDU's prev_id field. If the
receiving server does not recognise any of the prev_ids, it means an EDU
has been lost and the server should query a snapshot of the device list
via ``/user/keys/query`` in order to correctly interpret future ``m.device_list_update``
EDUs. May be missing or empty for the first EDU in a sequence.
items:
type: integer
description: |-
The stream_id of a prior EDU in this sequence which has not been referred
to already in an EDU's prev_id field.
example: 5
deleted:
type: boolean
description: |-
True if the server is announcing that this device has been deleted.
example: false
keys:
description: |-
The updated identity keys (if any) for this device. May be absent if the
device has no E2E keys defined.
$ref: ../../../client-server/definitions/device_keys.yaml
required:
- user_id
- device_id
- stream_id

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

@ -0,0 +1,75 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.direct_to_device
description: |-
An EDU that lets servers push send events directly to a specific device on
a remote server - for instance, to maintain an Olm E2E encrypted message channel
between a local and remote device.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.direct_to_device']
description: The string ``m.direct_to_device``.
example: "m.direct_to_device"
content:
type: object
description: The description of the direct-to-device message.
title: To Device Message
properties:
sender:
type: string
description: User ID of the sender.
example: "john@example.com"
type:
type: string
description: Event type for the message.
example: "m.room_key_request"
message_id:
type: string
description: Unique ID for the message, used for idempotence. Arbitrary
utf8 string, of maximum length 32 codepoints.
example: "hiezohf6Hoo7kaev"
messages:
type: object
description: |-
The contents of the messages to be sent. These are arranged in
a map of user IDs to a map of device IDs to message bodies.
The device ID may also be ``*``, meaning all known devices for the user.
additionalProperties:
type: object
title: User Devices
additionalProperties:
type: object
title: Device Message Contents
properties: {}
example: {
"alice@example.org": {
"IWHQUZUIAH": {
"algorithm": "m.megolm.v1.aes-sha2",
"room_id": "!Cuyf34gef24t:localhost",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
}
}
}
required:
- sender
- type
- message_id
- messages

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

@ -0,0 +1,71 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.presence
description: |-
An EDU representing presence updates for users of the sending homeserver.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.presence']
description: The string ``m.presence``
example: "m.presence"
content:
type: object
description: The presence updates and requests.
title: Presence Update
properties:
push:
type: array
description: |-
A list of presence updates that the receiving server is likely
to be interested in.
items:
type: object
title: User Presence Update
properties:
user_id:
type: string
description: The user ID this presence EDU is for.
example: "@john:matrix.org"
presence:
type: enum
enum: ['offline', 'unavailable', 'online']
description: The presence of the user.
example: "online"
status_msg:
type: string
description: An optional description to accompany the presence.
example: "Making cupcakes"
last_active_ago:
type: integer
format: int64
description: |-
The number of milliseconds that have elapsed since the user
last did something.
example: 5000
currently_active:
type: boolean
description: |-
True if the user is likely to be interacting with their
client. This may be indicated by the user having a
``last_active_ago`` within the last few minutes. Defaults
to false.
example: true
required: ['user_id', 'presence', 'last_active_ago']
required: ['push']

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

@ -0,0 +1,82 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.receipt
description: |-
An EDU representing receipt updates for users of the sending homeserver.
When receiving receipts, the server should only update entries that are
listed in the EDU. Receipts previously received that do not appear in the
EDU should not be removed or otherwise manipulated.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.receipt']
description: The string ``m.receipt``
example: "m.receipt"
content:
type: object
description: |-
Receipts for a particular room. The string key is the room ID for
which the receipts under it belong.
additionalProperties:
type: object
title: Room Receipts
properties:
# We strongly define the receipt type to help spec future ones later
# on. At that point, m.read can become optional (maybe).
"m.read":
type: object
description: Read receipts for users in the room.
title: User Read Receipt
properties:
event_ids:
type: array
description: |-
The extremity event IDs that the user has read up to.
minItems: 1
maxItems: 1
items:
type: string
example: ['$read_this_event:matrix.org']
data:
type: object
description: Metadata for the read receipt.
title: Read Receipt Metadata
properties:
ts:
type: integer
format: int64
description: |-
A POSIX timestamp in milliseconds for when the user read
the event specified in the read receipt.
example: 1533358089009
required: ['ts']
required: ['event_ids', 'data']
required: ['m.read']
example: {
"!some_room:example.org": {
"m.read": {
"@john:matrix.org": {
"event_ids": ["$read_this_event:matrix.org"],
"data": {
"ts": 1533358089009
}
}
}
}
}

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

@ -0,0 +1,64 @@
# 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: m.signing_key_update
description: |-
An EDU that lets servers push details to each other when one of their users
updates their cross-signing keys.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.signing_key_update']
description: The string ``m.signing_update``.
example: "m.signing_key_update"
content:
type: object
description: The updated signing keys.
title: Signing Key Update
properties:
user_id:
type: string
description: The user ID whose cross-signing keys have changed.
example: "@alice:example.com"
master_key:
type: object
$ref: ../../../client-server/definitions/cross_signing_key.yaml
example: {
"user_id": "@alice:example.com",
"usage": ["master"],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key",
}
}
self_signing_key:
type: object
$ref: ../../../client-server/definitions/cross_signing_key.yaml
example: {
"user_id": "@alice:example.com",
"usage": ["self_signing"],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
}
}
}
required:
- user_id

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

@ -0,0 +1,46 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.typing
description: A typing notification EDU for a user in a room.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.typing']
description: The string ``m.typing``
example: "m.typing"
content:
type: object
description: The typing notification.
title: Typing Notification
properties:
room_id:
type: string
description: |-
The room where the user's typing status has been updated.
example: "!somewhere:matrix.org"
user_id:
type: string
description: |-
The user ID that has had their typing status changed.
example: "@john:matrix.org"
typing:
type: boolean
description: Whether the user is typing in the room or not.
example: true
required: ['room_id', 'user_id', 'typing']