archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of github.com:matrix-org/matrix-doc

Browse Source
pull/977/head
Oddvar Lovaas 9 years ago
parent 054829f590 4f37e4ece0
commit 04c2fa23e3
33 changed files with 1302 additions and 1226 deletions
Show Stats Download Patch File Download Diff File

15
api/client-server/presence.yaml
Unescape Escape View File

@ -45,7 +45,7 @@ paths:
properties: properties:
presence: presence:
type: string type: string
enum: ["online", "offline", "unavailable", "free_for_chat"] enum: ["online", "offline", "unavailable"]
description: The new presence state. description: The new presence state.
status_msg: status_msg:
type: string type: string
@ -90,7 +90,7 @@ paths:
properties: properties:
presence: presence:
type: string type: string
enum: ["online", "offline", "unavailable", "free_for_chat"] enum: ["online", "offline", "unavailable"]
description: This user's presence. description: This user's presence.
last_active_ago: last_active_ago:
type: integer type: integer
@ -100,6 +100,10 @@ paths:
status_msg: status_msg:
type: [string, "null"] type: [string, "null"]
description: The state message for this user if one was set. description: The state message for this user if one was set.
currently_active:
type: boolean
description: "Whether the user is currently active"
required: ["presence"]
404: 404:
description: |- description: |-
There is no presence state for this user. This user may not exist or There is no presence state for this user. This user may not exist or
@ -181,8 +185,6 @@ paths:
[ [
{ {
"content": { "content": {
"avatar_url": "mxc://matrix.org/AfwefuigfWEfhuiPP",
"displayname": "Alice Margatroid",
"last_active_ago": 395, "last_active_ago": 395,
"presence": "offline", "presence": "offline",
"user_id": "@alice:matrix.org" "user_id": "@alice:matrix.org"
@ -191,11 +193,10 @@ paths:
}, },
{ {
"content": { "content": {
"avatar_url": "mxc://matrix.org/FWEhuiwegfWEfhuiwf",
"displayname": "Marisa Kirisame",
"last_active_ago": 16874, "last_active_ago": 16874,
"presence": "online", "presence": "online",
"user_id": "@marisa:matrix.org" "user_id": "@marisa:matrix.org",
"currently_active": true
}, },
"type": "m.presence" "type": "m.presence"
} }

6
api/client-server/pushrules.yaml
Unescape Escape View File

@ -360,7 +360,8 @@ paths:
x-example: someRuleId x-example: someRuleId
description: |- description: |-
Use 'before' with a ``rule_id`` as its value to make the new rule the Use 'before' with a ``rule_id`` as its value to make the new rule the
next-most important rule with respect to the given rule. next-most important rule with respect to the given user defined rule.
It is not possible to add a rule relative to a predefined server rule.
- in: query - in: query
type: string type: string
name: after name: after
@ -368,7 +369,8 @@ paths:
x-example: anotherRuleId x-example: anotherRuleId
description: |- description: |-
This makes the new rule the next-less important rule relative to the This makes the new rule the next-less important rule relative to the
given rule. given user defined rule. It is not possible to add a rule relative
to a predefined server rule.
- in: body - in: body
name: pushrule name: pushrule
description: |- description: |-

1
changelogs/client_server.rst
Unescape Escape View File

@ -7,6 +7,7 @@
federated aliases federated aliases
- ``GET /directory/room/{roomAlias}`` cannot return a 409; the ``PUT`` - ``GET /directory/room/{roomAlias}`` cannot return a 409; the ``PUT``
endpoint can, however. endpoint can, however.
- Clarify the behaviour of the ``m.room.power_levels`` event.
r0.1.0 r0.1.0
====== ======

1
event-schemas/examples/m.presence
Unescape Escape View File

@ -3,6 +3,7 @@
"avatar_url": "mxc://localhost:wefuiwegh8742w", "avatar_url": "mxc://localhost:wefuiwegh8742w",
"last_active_ago": 2478593, "last_active_ago": 2478593,
"presence": "online", "presence": "online",
"currently_active": false,
"user_id": "@example:localhost" "user_id": "@example:localhost"
}, },
"event_id": "$WLGTSEFSEF:localhost", "event_id": "$WLGTSEFSEF:localhost",

1
event-schemas/examples/m.room.power_levels
Unescape Escape View File

@ -7,6 +7,7 @@
"m.room.power_levels": 100 "m.room.power_levels": 100
}, },
"events_default": 0, "events_default": 0,
"invite": 50,
"kick": 50, "kick": 50,
"redact": 50, "redact": 50,
"state_default": 50, "state_default": 50,

6
event-schemas/schema/m.presence
Unescape Escape View File

@ -24,7 +24,11 @@
"presence": { "presence": {
"type": "string", "type": "string",
"description": "The presence state for this user.", "description": "The presence state for this user.",
"enum": ["online", "offline", "unavailable", "free_for_chat", "hidden"] "enum": ["online", "offline", "unavailable"]
},
"currently_active": {
"type": boolean,
"description": "Whether the user is currently active"
}, },
"user_id": { "user_id": {
"type": "string", "type": "string",

55
event-schemas/schema/m.room.aliases
Unescape Escape View File

@ -1,31 +1,24 @@
{ ---
"type": "object", allOf:
"title": "Informs the room about what room aliases it has been given.", - $ref: core-event-schema/state_event.yaml
"description": "This event is sent by a homeserver directly to inform of changes to the list of aliases it knows about for that room. The ``state_key`` for this event is set to the homeserver which owns the room alias. The entire set of known aliases for the room is the union of all the ``m.room.aliases`` events, one for each homeserver. Clients **should** check the validity of any room alias given in this list before presenting it to the user as trusted fact. The lists given by this event should be considered simply as advice on which aliases might exist, for which the client can perform the lookup to confirm whether it receives the correct room ID.", description: 'This event is sent by a homeserver directly to inform of changes to the list of aliases it knows about for that room. The ``state_key`` for this event is set to the homeserver which owns the room alias. The entire set of known aliases for the room is the union of all the ``m.room.aliases`` events, one for each homeserver. Clients **should** check the validity of any room alias given in this list before presenting it to the user as trusted fact. The lists given by this event should be considered simply as advice on which aliases might exist, for which the client can perform the lookup to confirm whether it receives the correct room ID.'
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { aliases:
"content": { description: A list of room aliases.
"type": "object", items:
"properties": { type: string
"aliases": { type: array
"type": "array", required:
"description": "A list of room aliases.", - aliases
"items": { type: object
"type": "string" state_key:
} description: The homeserver domain which owns these room aliases.
} type: string
}, type:
"required": ["aliases"] enum:
}, - m.room.aliases
"state_key": { type: string
"type": "string", title: Informs the room about what room aliases it has been given.
"description": "The homeserver domain which owns these room aliases." type: object
},
"type": {
"type": "string",
"enum": ["m.room.aliases"]
}
}
}

87
event-schemas/schema/m.room.avatar
Unescape Escape View File

@ -1,49 +1,38 @@
{ ---
"title": "RoomAvatar", allOf:
"description": "A picture that is associated with the room. This can be displayed alongside the room information.", - $ref: core-event-schema/state_event.yaml
"type": "object", description: A picture that is associated with the room. This can be displayed alongside the room information.
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { info:
"content": { allOf:
"type": "object", - $ref: core-event-schema/msgtype_infos/image_info.yaml
"properties": { description: Metadata about the image referred to in ``url``.
"url": { title: ImageInfo
"type": "string", type: object
"description": "The URL to the image." thumbnail_info:
}, allOf:
"thumbnail_url": { - $ref: core-event-schema/msgtype_infos/image_info.yaml
"type": "string", description: Metadata about the image referred to in ``thumbnail_url``.
"description": "The URL to the thumbnail of the image." title: ImageInfo
}, type: object
"thumbnail_info": { thumbnail_url:
"type": "object", description: The URL to the thumbnail of the image.
"title": "ImageInfo", type: string
"description": "Metadata about the image referred to in ``thumbnail_url``.", url:
"allOf": [{ description: The URL to the image.
"$ref": "core-event-schema/msgtype_infos/image_info.yaml" type: string
}] required:
}, - url
"info": { type: object
"type": "object", state_key:
"title": "ImageInfo", description: A zero-length string.
"description": "Metadata about the image referred to in ``url``.", pattern: '^$'
"allOf": [{ type: string
"$ref": "core-event-schema/msgtype_infos/image_info.yaml" type:
}] enum:
} - m.room.avatar
}, type: string
"required": ["url"] title: RoomAvatar
}, type: object
"state_key": {
"type": "string",
"description": "A zero-length string.",
"pattern": "^$"
},
"type": {
"type": "string",
"enum": ["m.room.avatar"]
}
}
}

49
event-schemas/schema/m.room.canonical_alias
Unescape Escape View File

@ -1,28 +1,21 @@
{ ---
"type": "object", allOf:
"title": "Informs the room as to which alias is the canonical one.", - $ref: core-event-schema/state_event.yaml
"description": "This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.", description: This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { alias:
"content": { description: The canonical alias.
"type": "object", type: string
"properties": { type: object
"alias": { state_key:
"type": "string", description: A zero-length string.
"description": "The canonical alias." pattern: '^$'
} type: string
} type:
}, enum:
"state_key": { - m.room.canonical_alias
"type": "string", type: string
"description": "A zero-length string.", title: Informs the room as to which alias is the canonical one.
"pattern": "^$" type: object
},
"type": {
"type": "string",
"enum": ["m.room.canonical_alias"]
}
}
}

59
event-schemas/schema/m.room.create
Unescape Escape View File

@ -1,33 +1,26 @@
{ ---
"type": "object", allOf:
"title": "The first event in the room.", - $ref: core-event-schema/state_event.yaml
"description": "This is the first event in a room and cannot be changed. It acts as the root of all other events.", description: This is the first event in a room and cannot be changed. It acts as the root of all other events.
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { creator:
"content": { description: The ``user_id`` of the room creator. This is set by the homeserver.
"type": "object", type: string
"properties": { m.federate:
"creator": { description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist.
"type": "string", type: boolean
"description": "The ``user_id`` of the room creator. This is set by the homeserver." required:
}, - creator
"m.federate": { type: object
"type": "boolean", state_key:
"description": "Whether users on other servers can join this room. Defaults to ``true`` if key does not exist." description: A zero-length string.
} pattern: '^$'
}, type: string
"required": ["creator"] type:
}, enum:
"state_key": { - m.room.create
"type": "string", type: string
"description": "A zero-length string.", title: The first event in the room.
"pattern": "^$" type: object
},
"type": {
"type": "string",
"enum": ["m.room.create"]
}
}
}

56
event-schemas/schema/m.room.guest_access
Unescape Escape View File

@ -1,30 +1,26 @@
{ ---
"type": "object", allOf:
"title": "Controls whether guest users are allowed to join rooms.", - $ref: core-event-schema/state_event.yaml
"description": "This event controls whether guest users are allowed to join rooms. If this event is absent, servers should act as if it is present and has the guest_access value \"forbidden\".", description: 'This event controls whether guest users are allowed to join rooms. If this event is absent, servers should act as if it is present and has the guest_access value "forbidden".'
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { guest_access:
"content": { description: Whether guests can join the room.
"type": "object", enum:
"properties": { - can_join
"guest_access": { - forbidden
"type": "string", type: string
"description": "Whether guests can join the room.", required:
"enum": ["can_join", "forbidden"] - guest_access
} type: object
}, state_key:
"required": ["guest_access"] description: A zero-length string.
}, pattern: '^$'
"state_key": { type: string
"type": "string", type:
"description": "A zero-length string.", enum:
"pattern": "^$" - m.room.guest_access
}, type: string
"type": { title: Controls whether guest users are allowed to join rooms.
"type": "string", type: object
"enum": ["m.room.guest_access"]
}
}
}

58
event-schemas/schema/m.room.history_visibility
Unescape Escape View File

@ -1,30 +1,28 @@
{ ---
"type": "object", allOf:
"title": "Controls visibility of history.", - $ref: core-event-schema/state_event.yaml
"description": "This event controls whether a user can see the events that happened in a room from before they joined.", description: This event controls whether a user can see the events that happened in a room from before they joined.
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { history_visibility:
"content": { description: Who can see the room history.
"type": "object", enum:
"properties": { - invited
"history_visibility": { - joined
"type": "string", - shared
"description": "Who can see the room history.", - world_readable
"enum": ["invited","joined","shared","world_readable"] type: string
} required:
}, - history_visibility
"required": ["history_visibility"] type: object
}, state_key:
"state_key": { description: A zero-length string.
"type": "string", pattern: '^$'
"description": "A zero-length string.", type: string
"pattern": "^$" type:
}, enum:
"type": { - m.room.history_visibility
"type": "string", type: string
"enum": ["m.room.history_visibility"] title: Controls visibility of history.
} type: object
}
}

58
event-schemas/schema/m.room.join_rules
Unescape Escape View File

@ -1,30 +1,28 @@
{ ---
"type": "object", allOf:
"title": "Describes how users are allowed to join the room.", - $ref: core-event-schema/state_event.yaml
"description": "A room may be ``public`` meaning anyone can join the room without any prior action. Alternatively, it can be ``invite`` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, ``knock`` and ``private`` are reserved keywords which are not implemented.", description: 'A room may be ``public`` meaning anyone can join the room without any prior action. Alternatively, it can be ``invite`` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, ``knock`` and ``private`` are reserved keywords which are not implemented.'
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { join_rule:
"content": { description: The type of rules used for users wishing to join this room.
"type": "object", enum:
"properties": { - public
"join_rule": { - knock
"type": "string", - invite
"description": "The type of rules used for users wishing to join this room.", - private
"enum": ["public","knock","invite","private"] type: string
} required:
}, - join_rule
"required": ["join_rule"] type: object
}, state_key:
"state_key": { description: A zero-length string.
"type": "string", pattern: '^$'
"description": "A zero-length string.", type: string
"pattern": "^$" type:
}, enum:
"type": { - m.room.join_rules
"type": "string", type: string
"enum": ["m.room.join_rules"] title: Describes how users are allowed to join the room.
} type: object
}
}

200
event-schemas/schema/m.room.member
Unescape Escape View File

@ -1,95 +1,105 @@
{ ---
"type": "object", allOf:
"title": "The current membership state of a user in the room.", - $ref: core-event-schema/state_event.yaml
"description": "Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. \n\nThe following membership states are specified:\n\n- ``invite`` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.\n\n- ``join`` - The user has joined the room (possibly after accepting an invite), and may participate in it.\n\n- ``leave`` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).\n\n- ``ban`` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ``ban``).\n\n- ``knock`` - This is a reserved word, which currently has no meaning.\n\nThe ``third_party_invite`` property will be set if this invite is an ``invite`` event and is the successor of an ``m.room.third_party_invite`` event, and absent otherwise.\n\nThis event may also include an ``invite_room_state`` key **outside the** ``content`` **key**. If present, this contains an array of ``StrippedState`` Events. These events provide information on a subset of state events such as the room name.", description: |-
"allOf": [{ Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
"$ref": "core-event-schema/state_event.yaml"
}], The following membership states are specified:
"properties": {
"content": { - ``invite`` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
"type": "object",
"title": "EventContent", - ``join`` - The user has joined the room (possibly after accepting an invite), and may participate in it.
"properties": {
"membership": { - ``leave`` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
"type": "string",
"description": "The membership state of the user.", - ``ban`` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ``ban``).
"enum": ["invite","join","knock","leave","ban"]
}, - ``knock`` - This is a reserved word, which currently has no meaning.
"avatar_url": {
"type": "string", The ``third_party_invite`` property will be set if this invite is an ``invite`` event and is the successor of an ``m.room.third_party_invite`` event, and absent otherwise.
"description": "The avatar URL for this user, if any. This is added by the homeserver."
}, This event may also include an ``invite_room_state`` key **outside the** ``content`` **key**. If present, this contains an array of ``StrippedState`` Events. These events provide information on a subset of state events such as the room name.
"displayname": { properties:
"type": ["string", "null"], content:
"description": "The display name for this user, if any. This is added by the homeserver." properties:
}, avatar_url:
"third_party_invite": { description: 'The avatar URL for this user, if any. This is added by the homeserver.'
"type": "object", type: string
"title": "Invite", displayname:
"properties": { description: 'The display name for this user, if any. This is added by the homeserver.'
"display_name": { type:
"type": "string", - "string"
"description": "A name which can be displayed to represent the user instead of their third party identifier" - "null"
}, membership:
"signed": { description: The membership state of the user.
"type": "object", enum:
"title": "signed", - invite
"description": "A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.", - join
"properties": { - knock
"mxid": { - leave
"type": "string", - ban
"description": "The invited matrix user ID. Must be equal to the user_id property of the event." type: string
}, third_party_invite:
"token": { properties:
"type": "string", display_name:
"description": "The token property of the containing third_party_invite object." description: A name which can be displayed to represent the user instead of their third party identifier
}, type: string
"signatures": { signed:
"type": "object", description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.'
"description": "A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.", properties:
"title": "Signatures" mxid:
} description: The invited matrix user ID. Must be equal to the user_id property of the event.
}, type: string
"required": ["mxid", "signatures", "token"] signatures:
} description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.'
}, title: Signatures
"required": ["display_name", "signed"] type: object
} token:
}, description: The token property of the containing third_party_invite object.
"required": ["membership"] type: string
}, required:
"state_key": { - mxid
"type": "string", - signatures
"description": "The ``user_id`` this membership event relates to." - token
}, title: signed
"type": { type: object
"type": "string", required:
"enum": ["m.room.member"] - display_name
}, - signed
"invite_room_state": { title: Invite
"type": "array", type: object
"description": "A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.", required:
"items": { - membership
"type": "object", title: EventContent
"title": "StrippedState", type: object
"description": "A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.", invite_room_state:
"required": ["type", "state_key", "content"], description: 'A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.'
"properties": { items:
"type": { description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.'
"type": "string", properties:
"description": "The ``type`` for the event." content:
}, description: The ``content`` for the event.
"state_key": { title: EventContent
"type": "string", type: object
"description": "The ``state_key`` for the event." state_key:
}, description: The ``state_key`` for the event.
"content": { type: string
"title": "EventContent", type:
"type": "object", description: The ``type`` for the event.
"description": "The ``content`` for the event." type: string
} required:
} - type
} - state_key
} - content
} title: StrippedState
} type: object
type: array
state_key:
description: The ``user_id`` this membership event relates to.
type: string
type:
enum:
- m.room.member
type: string
title: The current membership state of a user in the room.
type: object

51
event-schemas/schema/m.room.message
Unescape Escape View File

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

93
event-schemas/schema/m.room.message#m.audio
Unescape Escape View File

@ -1,51 +1,42 @@
{ ---
"type": "object", allOf:
"title": "AudioMessage", - $ref: core-event-schema/room_event.yaml
"description": "This message represents a single audio clip.", description: This message represents a single audio clip.
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'."
"type": "object", type: string
"properties": { info:
"msgtype": { description: Metadata for the audio clip referred to in ``url``.
"type": "string", properties:
"enum": ["m.audio"] duration:
}, description: The duration of the audio in milliseconds.
"body": { type: integer
"type": "string", mimetype:
"description": "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'." description: The mimetype of the audio e.g. ``audio/aac``.
}, type: string
"url": { size:
"type": "string", description: The size of the audio clip in bytes.
"description": "The URL to the audio clip." type: integer
}, title: AudioInfo
"info": { type: object
"type": "object", msgtype:
"title": "AudioInfo", enum:
"description": "Metadata for the audio clip referred to in ``url``.", - m.audio
"properties": { type: string
"mimetype": { url:
"type": "string", description: The URL to the audio clip.
"description": "The mimetype of the audio e.g. ``audio/aac``." type: string
}, required:
"size": { - msgtype
"type": "integer", - body
"description": "The size of the audio clip in bytes." - url
}, type: object
"duration": { type:
"type": "integer", enum:
"description": "The duration of the audio in milliseconds." - m.room.message
} type: string
} title: AudioMessage
} type: object
},
"required": ["msgtype", "body", "url"]
},
"type": {
"type": "string",
"enum": ["m.room.message"]
}
}
}

52
event-schemas/schema/m.room.message#m.emote
Unescape Escape View File

@ -1,28 +1,24 @@
{ ---
"type": "object", allOf:
"title": "EmoteMessage", - $ref: core-event-schema/room_event.yaml
"description": "This message is similar to ``m.text`` except that the sender is 'performing' the action contained in the ``body`` key, similar to ``/me`` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular ``m.text`` messages.", description: "This message is similar to ``m.text`` except that the sender is 'performing' the action contained in the ``body`` key, similar to ``/me`` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular ``m.text`` messages."
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: The emote action to perform.
"type": "object", type: string
"properties": { msgtype:
"msgtype": { enum:
"type": "string", - m.emote
"enum": ["m.emote"] type: string
}, required:
"body": { - msgtype
"type": "string", - body
"description": "The emote action to perform." type: object
} type:
}, enum:
"required": ["msgtype", "body"] - m.room.message
}, type: string
"type": { title: EmoteMessage
"type": "string", type: object
"enum": ["m.room.message"]
}
}
}

115
event-schemas/schema/m.room.message#m.file
Unescape Escape View File

@ -1,63 +1,52 @@
{ ---
"type": "object", allOf:
"title": "FileMessage", - $ref: core-event-schema/room_event.yaml
"description": "This message represents a generic file.", description: This message represents a generic file.
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: A human-readable description of the file. This is recommended to be the filename of the original upload.
"type": "object", type: string
"properties": { filename:
"msgtype": { description: The original filename of the uploaded file.
"type": "string", type: string
"enum": ["m.file"] info:
}, description: Information about the file referred to in ``url``.
"filename": { properties:
"type": "string", mimetype:
"description": "The original filename of the uploaded file." description: The mimetype of the file e.g. ``application/msword``.
}, type: string
"body": { size:
"type": "string", description: The size of the file in bytes.
"description": "A human-readable description of the file. This is recommended to be the filename of the original upload." type: integer
}, title: FileInfo
"url": { type: object
"type": "string", msgtype:
"description": "The URL to the file." enum:
}, - m.file
"info": { type: string
"type": "object", thumbnail_info:
"title": "FileInfo", allOf:
"description": "Information about the file referred to in ``url``.", - $ref: core-event-schema/msgtype_infos/image_info.yaml
"properties": { description: Metadata about the image referred to in ``thumbnail_url``.
"size": { title: ImageInfo
"type": "integer", type: object
"description": "The size of the file in bytes." thumbnail_url:
}, description: The URL to the thumbnail of the file.
"mimetype": { type: string
"type": "string", url:
"description": "The mimetype of the file e.g. ``application/msword``." description: The URL to the file.
} type: string
} required:
}, - msgtype
"thumbnail_url": { - body
"type": "string", - url
"description": "The URL to the thumbnail of the file." - filename
}, type: object
"thumbnail_info": { type:
"type": "object", enum:
"title": "ImageInfo", - m.room.message
"description": "Metadata about the image referred to in ``thumbnail_url``.", type: string
"allOf": [{ title: FileMessage
"$ref": "core-event-schema/msgtype_infos/image_info.yaml" type: object
}]
}
},
"required": ["msgtype", "body", "url", "filename"]
},
"type": {
"type": "string",
"enum": ["m.room.message"]
}
}
}

121
event-schemas/schema/m.room.message#m.image
Unescape Escape View File

@ -1,67 +1,54 @@
{ ---
"type": "object", allOf:
"title": "ImageMessage", - $ref: core-event-schema/room_event.yaml
"description": "This message represents a single image and an optional thumbnail.", description: This message represents a single image and an optional thumbnail.
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: "A textual representation of the image. This could be the alt text of the image, the filename of the image, or some kind of content description for accessibility e.g. 'image attachment'."
"type": "object", type: string
"properties": { info:
"msgtype": { description: Metadata about the image referred to in ``url``.
"type": "string", properties:
"enum": ["m.image"] h:
}, description: The height of the image in pixels.
"body": { type: integer
"type": "string", mimetype:
"description": "A textual representation of the image. This could be the alt text of the image, the filename of the image, or some kind of content description for accessibility e.g. 'image attachment'." description: 'The mimetype of the image, e.g. ``image/jpeg``.'
}, type: string
"url": { size:
"type": "string", description: Size of the image in bytes.
"description": "The URL to the image." type: integer
}, w:
"thumbnail_url": { description: The width of the image in pixels.
"type": "string", type: integer
"description": "The URL to the thumbnail of the image." title: ImageInfo
}, type: object
"thumbnail_info": { msgtype:
"type": "object", enum:
"title": "ImageInfo", - m.image
"description": "Metadata about the image referred to in ``thumbnail_url``.", type: string
"allOf": [{ thumbnail_info:
"$ref": "core-event-schema/msgtype_infos/image_info.yaml" allOf:
}] - $ref: core-event-schema/msgtype_infos/image_info.yaml
}, description: Metadata about the image referred to in ``thumbnail_url``.
"info": { title: ImageInfo
"type": "object", type: object
"title": "ImageInfo", thumbnail_url:
"description": "Metadata about the image referred to in ``url``.", description: The URL to the thumbnail of the image.
"properties": { type: string
"size": { url:
"type": "integer", description: The URL to the image.
"description": "Size of the image in bytes." type: string
}, required:
"w": { - msgtype
"type": "integer", - body
"description": "The width of the image in pixels." - url
}, type: object
"h": { type:
"type": "integer", enum:
"description": "The height of the image in pixels." - m.room.message
}, type: string
"mimetype": { title: ImageMessage
"type": "string", type: object
"description": "The mimetype of the image, e.g. ``image/jpeg``."
}
}
}
},
"required": ["msgtype", "body", "url"]
},
"type": {
"type": "string",
"enum": ["m.room.message"]
}
}
}

79
event-schemas/schema/m.room.message#m.location
Unescape Escape View File

@ -1,43 +1,36 @@
{ ---
"type": "object", allOf:
"title": "LocationMessage", - $ref: core-event-schema/room_event.yaml
"description": "This message represents a real-world location.", description: This message represents a real-world location.
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: "A description of the location e.g. 'Big Ben, London, UK', or some kind of content description for accessibility e.g. 'location attachment'."
"type": "object", type: string
"properties": { geo_uri:
"msgtype": { description: A geo URI representing this location.
"type": "string", type: string
"enum": ["m.location"] msgtype:
}, enum:
"body": { - m.location
"type": "string", type: string
"description": "A description of the location e.g. 'Big Ben, London, UK', or some kind of content description for accessibility e.g. 'location attachment'." thumbnail_info:
}, allOf:
"geo_uri": { - $ref: core-event-schema/msgtype_infos/image_info.yaml
"type": "string", title: ImageInfo
"description": "A geo URI representing this location." type: object
}, thumbnail_url:
"thumbnail_url": { description: The URL to a thumbnail of the location being represented.
"type": "string", type: string
"description": "The URL to a thumbnail of the location being represented." required:
}, - msgtype
"thumbnail_info": { - body
"type": "object", - geo_uri
"title": "ImageInfo", type: object
"allOf": [{ type:
"$ref": "core-event-schema/msgtype_infos/image_info.yaml" enum:
}] - m.room.message
} type: string
}, title: LocationMessage
"required": ["msgtype", "body", "geo_uri"] type: object
},
"type": {
"type": "string",
"enum": ["m.room.message"]
}
}
}

52
event-schemas/schema/m.room.message#m.notice
Unescape Escape View File

@ -1,28 +1,24 @@
{ ---
"type": "object", allOf:
"title": "NoticeMessage", - $ref: core-event-schema/room_event.yaml
"description": "A m.notice message should be considered similar to a plain m.text message except that clients should visually distinguish it in some way. It is intended to be used by automated clients, such as bots, bridges, and other entities, rather than humans. Additionally, such automated agents which watch a room for messages and respond to them ought to ignore m.notice messages. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages, as each responds to the other.", description: 'A m.notice message should be considered similar to a plain m.text message except that clients should visually distinguish it in some way. It is intended to be used by automated clients, such as bots, bridges, and other entities, rather than humans. Additionally, such automated agents which watch a room for messages and respond to them ought to ignore m.notice messages. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages, as each responds to the other.'
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: The notice text to send.
"type": "object", type: string
"properties": { msgtype:
"msgtype": { enum:
"type": "string", - m.notice
"enum": ["m.notice"] type: string
}, required:
"body": { - msgtype
"type": "string", - body
"description": "The notice text to send." type: object
} type:
}, enum:
"required": ["msgtype", "body"] - m.room.message
}, type: string
"type": { title: NoticeMessage
"type": "string", type: object
"enum": ["m.room.message"]
}
}
}

52
event-schemas/schema/m.room.message#m.text
Unescape Escape View File

@ -1,28 +1,24 @@
{ ---
"type": "object", allOf:
"title": "TextMessage", - $ref: core-event-schema/room_event.yaml
"description": "This message is the most basic message and is used to represent text.", description: This message is the most basic message and is used to represent text.
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: The body of the message.
"type": "object", type: string
"properties": { msgtype:
"msgtype": { enum:
"type": "string", - m.text
"enum": ["m.text"] type: string
}, required:
"body": { - msgtype
"type": "string", - body
"description": "The body of the message." type: object
} type:
}, enum:
"required": ["msgtype", "body"] - m.room.message
}, type: string
"type": { title: TextMessage
"type": "string", type: object
"enum": ["m.room.message"]
}
}
}

126
event-schemas/schema/m.room.message#m.video
Unescape Escape View File

@ -1,70 +1,56 @@
{ ---
"type": "object", allOf:
"title": "VideoMessage", - $ref: core-event-schema/room_event.yaml
"description": "This message represents a single video clip.", description: This message represents a single video clip.
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { body:
"content": { description: "A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'."
"type": "object", type: string
"properties": { info:
"msgtype": { description: Metadata about the video clip referred to in ``url``.
"type": "string", properties:
"enum": ["m.video"] duration:
}, description: The duration of the video in milliseconds.
"body": { type: integer
"type": "string", h:
"description": "A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'." description: The height of the video in pixels.
}, type: integer
"url": { mimetype:
"type": "string", description: The mimetype of the video e.g. ``video/mp4``.
"description": "The URL to the video clip." type: string
}, size:
"info": { description: The size of the video in bytes.
"type": "object", type: integer
"title": "VideoInfo", thumbnail_info:
"description": "Metadata about the video clip referred to in ``url``.", allOf:
"properties": { - $ref: core-event-schema/msgtype_infos/image_info.yaml
"mimetype": { title: ImageInfo
"type": "string", type: object
"description": "The mimetype of the video e.g. ``video/mp4``." thumbnail_url:
}, description: The URL to a thumbnail of the video clip.
"size": { type: string
"type": "integer", w:
"description": "The size of the video in bytes." description: The width of the video in pixels.
}, type: integer
"duration": { title: VideoInfo
"type": "integer", type: object
"description": "The duration of the video in milliseconds." msgtype:
}, enum:
"w": { - m.video
"type": "integer", type: string
"description": "The width of the video in pixels." url:
}, description: The URL to the video clip.
"h": { type: string
"type": "integer", required:
"description": "The height of the video in pixels." - msgtype
}, - body
"thumbnail_url": { - url
"type": "string", type: object
"description": "The URL to a thumbnail of the video clip." type:
}, enum:
"thumbnail_info": { - m.room.message
"type": "object", type: string
"title": "ImageInfo", title: VideoMessage
"allOf": [{ type: object
"$ref": "core-event-schema/msgtype_infos/image_info.yaml"
}]
}
}
}
},
"required": ["msgtype", "body", "url"]
},
"type": {
"type": "string",
"enum": ["m.room.message"]
}
}
}

55
event-schemas/schema/m.room.message.feedback
Unescape Escape View File

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

52
event-schemas/schema/m.room.name
Unescape Escape View File

@ -1,29 +1,23 @@
{ ---
"title": "RoomName", allOf:
"description": "A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set. The room name can also be set when creating a room using ``/createRoom`` with the ``name`` key.", - $ref: core-event-schema/state_event.yaml
"type": "object", description: 'A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set. The room name can also be set when creating a room using ``/createRoom`` with the ``name`` key.'
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { name:
"content": { description: The name of the room. This MUST NOT exceed 255 bytes.
"type": "object", type: string
"properties": { required:
"name": { - name
"type": "string", type: object
"description": "The name of the room. This MUST NOT exceed 255 bytes." state_key:
} description: A zero-length string.
}, pattern: '^$'
"required": ["name"] type: string
}, type:
"state_key": { enum:
"type": "string", - m.room.name
"description": "A zero-length string.", type: string
"pattern": "^$" title: RoomName
}, type: object
"type": {
"type": "string",
"enum": ["m.room.name"]
}
}
}

156
event-schemas/schema/m.room.power_levels
Unescape Escape View File

@ -1,70 +1,86 @@
{ ---
"type": "object", allOf:
"title": "Defines the power levels (privileges) of users in the room.", - $ref: core-event-schema/state_event.yaml
"description": "This event specifies the minimum level a user must have in order to perform a certain action. It also specifies the levels of each user in the room.\n\nIf a ``user_id`` is in the ``users`` list, then that ``user_id`` has the associated power level. Otherwise they have the default level ``users_default``. If ``users_default`` is not supplied, it is assumed to be 0.\n\nThe level required to send a certain event is governed by ``events``, ``state_default`` and ``events_default``. If an event type is specified in ``events``, then the user must have at least the level specified in order to send that event. If the event type is not supplied, it defaults to ``events_default`` for Message Events and ``state_default`` for State Events. If there is no ``state_default`` in the ``power_levels`` event, the ``state_default`` is 50. If the room contains no ``power_levels`` event, the ``state_default`` is 0. The ``events_default`` is 0 in either of these cases.", description: |-
"allOf": [{ This event specifies the minimum level a user must have in order to perform a
"$ref": "core-event-schema/state_event.yaml" certain action. It also specifies the levels of each user in the room.
}],
"properties": { If a ``user_id`` is in the ``users`` list, then that ``user_id`` has the
"content": { associated power level. Otherwise they have the default level
"type": "object", ``users_default``. If ``users_default`` is not supplied, it is assumed to be
"properties": { 0.
"ban": {
"type": "number", The level required to send a certain event is governed by ``events``,
"description": "The level required to ban a user." ``state_default`` and ``events_default``. If an event type is specified in
}, ``events``, then the user must have at least the level specified in order to
"events_default": { send that event. If the event type is not supplied, it defaults to
"type": "number", ``events_default`` for Message Events and ``state_default`` for State
"description": "The default level required to send message events. Can be overridden by the ``events`` key." Events.
},
"kick": { If there is no ``state_default`` in the ``m.room.power_levels`` event, the
"type": "number", ``state_default`` is 50. If there is no ``events_default`` in the
"description": "The level required to kick a user." ``m.room.power_levels`` event, the ``events_default`` is 0. If the room
}, contains no ``m.room.power_levels`` event, *both* the ``state_default`` and
"redact": { ``events_default`` are 0.
"type": "number",
"description": "The level required to redact an event." The power level required to invite a user to the room, kick a user from the
}, room, ban a user from the room, or redact an event, is defined by ``invite``,
"invite": { ``kick``, ``ban``, and ``redact``, respectively. Each of these levels defaults
"type": "number", to 50 if they are not specified in the ``m.room.power_levels`` event, or if
"description": "The level required to invite a user." the room contains no ``m.room.power_levels`` event.
},
"state_default": { properties:
"type": "number", content:
"description": "The default level required to send state events. Can be overridden by the ``events`` key." properties:
}, ban:
"users_default": { description: The level required to ban a user. Defaults to 50 if unspecified.
"type": "number", type: number
"description": "The default power level for every user in the room, unless their ``user_id`` is mentioned in the ``users`` key." events:
}, additionalProperties:
"events": { type: number
"type": "object", description: The level required to send specific event types. This is a mapping from event type to power level required.
"title": "Event power levels", title: Event power levels
"description": "The level required to send specific event types. This is a mapping from event type to power level required.", type: object
"additionalProperties": { events_default:
"type": "number" description: |-
} The default level required to send message events. Can be
}, overridden by the ``events`` key. Defaults to 0 if unspecified.
"users": { type: number
"type": "object", invite:
"title": "User power levels", description: The level required to invite a user. Defaults to 50 if unspecified.
"description": "The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.", type: number
"additionalProperties": { kick:
"type": "number" description: The level required to kick a user. Defaults to 50 if unspecified.
} type: number
} redact:
}, description: The level required to redact an event. Defaults to 50 if unspecified.
"required": ["ban","events","events_default","kick","redact", type: number
"state_default","users"] state_default:
}, description: |-
"state_key": { The default level required to send state events. Can be overridden
"type": "string", by the ``events`` key. Defaults to 50 if unspecified, but 0 if
"description": "A zero-length string.", there is no ``m.room.power_levels`` event at all.
"pattern": "^$" type: number
}, users:
"type": { additionalProperties:
"type": "string", type: number
"enum": ["m.room.power_levels"] description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.
} title: User power levels
} type: object
} users_default:
description: |-
The default power level for every user in the room, unless their
``user_id`` is mentioned in the ``users`` key. Defaults to 0 if
unspecified.
type: number
type: object
state_key:
description: A zero-length string.
pattern: '^$'
type: string
type:
enum:
- m.room.power_levels
type: string
title: Defines the power levels (privileges) of users in the room.
type: object

50
event-schemas/schema/m.room.redaction
Unescape Escape View File

@ -1,28 +1,22 @@
{ ---
"type": "object", allOf:
"title": "Redaction", - $ref: core-event-schema/room_event.yaml
"description": "Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data. There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the ``redacts`` event level key.", description: 'Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data. There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the ``redacts`` event level key.'
"allOf": [{ properties:
"$ref": "core-event-schema/room_event.yaml" content:
}], properties:
"properties": { reason:
"content": { description: 'The reason for the redaction, if any.'
"type": "object", type: string
"properties": { type: object
"reason": { redacts:
"type": "string", description: The event ID that was redacted.
"description": "The reason for the redaction, if any." type: string
} type:
} enum:
}, - m.room.redaction
"redacts": { type: string
"type": "string", required:
"description": "The event ID that was redacted." - redacts
}, title: Redaction
"type": { type: object
"type": "string",
"enum": ["m.room.redaction"]
}
},
"required": ["redacts"]
}

102
event-schemas/schema/m.room.third_party_invite
Unescape Escape View File

@ -1,56 +1,46 @@
{ ---
"$schema": "http://json-schema.org/draft-04/schema#", $schema: http://json-schema.org/draft-04/schema#
"type": "object", allOf:
"title": "An invitation to a room issued to a third party identifier, rather than a matrix user ID.", - $ref: core-event-schema/state_event.yaml
"description": "Acts as an ``m.room.member`` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room.", description: "Acts as an ``m.room.member`` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room."
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { display_name:
"content": { description: "A user-readable string which represents the user who has been invited. This should not contain the user's third party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third party ID."
"type": "object", type: string
"properties": { key_validity_url:
"display_name": { description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'."
"type": "string", type: string
"description": "A user-readable string which represents the user who has been invited. This should not contain the user's third party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third party ID." public_key:
}, description: A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility.
"key_validity_url": { type: string
"type": "string", public_keys:
"description": "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'." description: Keys with which the token may be signed.
}, items:
"public_key": { properties:
"type": "string", key_validity_url:
"description": "A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility." description: "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely."
}, type: string
"public_keys": { public_key:
"type": "array", description: A base-64 encoded ed25519 key with which token may be signed.
"description": "Keys with which the token may be signed.", type: string
"items": { required:
"type": "object", - public_key
"title": "PublicKeys", title: PublicKeys
"properties": { type: object
"public_key": { type: array
"type": "string", required:
"description": "A base-64 encoded ed25519 key with which token may be signed." - display_name
}, - key_validity_url
"key_validity_url": { - public_key
"type": "string", type: object
"description": "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely." state_key:
} description: 'The token, of which a signature must be produced in order to join the room.'
}, type: string
"required": ["public_key"] type:
} enum:
} - m.room.third_party_invite
}, type: string
"required": ["display_name", "key_validity_url", "public_key"] title: 'An invitation to a room issued to a third party identifier, rather than a matrix user ID.'
}, type: object
"state_key": {
"type": "string",
"description": "The token, of which a signature must be produced in order to join the room."
},
"type": {
"type": "string",
"enum": ["m.room.third_party_invite"]
}
}
}

52
event-schemas/schema/m.room.topic
Unescape Escape View File

@ -1,29 +1,23 @@
{ ---
"type": "object", allOf:
"title": "Topic", - $ref: core-event-schema/state_event.yaml
"description": "A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using ``/createRoom`` with the ``topic`` key.", description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using ``/createRoom`` with the ``topic`` key.'
"allOf": [{ properties:
"$ref": "core-event-schema/state_event.yaml" content:
}], properties:
"properties": { topic:
"content": { description: The topic text.
"type": "object", type: string
"properties": { required:
"topic": { - topic
"type": "string", type: object
"description": "The topic text." state_key:
} description: A zero-length string.
}, pattern: '^$'
"required": ["topic"] type: string
}, type:
"state_key": { enum:
"type": "string", - m.room.topic
"description": "A zero-length string.", type: string
"pattern": "^$" title: Topic
}, type: object
"type": {
"type": "string",
"enum": ["m.room.topic"]
}
}
}

79
specification/modules/presence.rst
Unescape Escape View File

@ -20,7 +20,7 @@ membership of a room.
A presence list is a list of user IDs whose presence the user wants to follow. A presence list is a list of user IDs whose presence the user wants to follow.
To be added to this list, the user being added must be invited by the list owner To be added to this list, the user being added must be invited by the list owner
who must accept the invitation. who must accept the invitation.
User's presence state is represented by the ``presence`` key, which is an enum User's presence state is represented by the ``presence`` key, which is an enum
of one of the following: of one of the following:
@ -30,8 +30,6 @@ of one of the following:
idle. idle.
- ``offline`` : The user is not connected to an event stream or is - ``offline`` : The user is not connected to an event stream or is
explicitly suppressing their profile information from being sent. explicitly suppressing their profile information from being sent.
- ``free_for_chat`` : The user is generally willing to receive messages
moreso than default.
Events Events
------ ------
@ -46,67 +44,44 @@ listed below.
{{presence_cs_http_api}} {{presence_cs_http_api}}
Idle timeout
~~~~~~~~~~~~
Clients SHOULD implement an "idle timeout". This is a timer which fires after
a period of inactivity on the client. The definition of inactivity varies
depending on the client. For example, web implementations may determine
inactivity to be not moving the mouse for a certain period of time. When this
timer fires it should set the presence state to ``unavailable``. When the user
becomes active again (e.g. by moving the mouse) the client should set the
presence state to ``online``. A timeout value between 1 and 5 minutes is
recommended.
Server behaviour Server behaviour
---------------- ----------------
Each user's homeserver stores a "presence list" per user. Once a user accepts Each user's homeserver stores a "presence list" per user. Once a user accepts
a presence list, both user's HSes must track the subscription. a presence list, both user's HSes must track the subscription.
Propagating profile information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because the profile display name and avatar information are likely to be used in
many places of a client's display, changes to these fields SHOULD cause an
automatic propagation event to occur, informing likely-interested parties of the
new values. One of these change mechanisms SHOULD be via ``m.presence`` events.
These events should set ``displayname`` and ``avatar_url`` to the new values
along with the presence-specific keys. This SHOULD be done automatically by the
homeserver when a user successfully changes their display name or avatar URL.
.. admonition:: Rationale
The intention for sending this information in ``m.presence`` is so that any
"user list" can display the *current* name/presence for a user ID outside the
scope of a room e.g. for a user page. This is bundled into a single event for
several reasons. The user's display name can change per room. This
event provides the "canonical" name for the user. In addition, the name is
bundled into a single event for the ease of client implementations. If this
was not done, the client would need to search all rooms for their own
membership event to pull out the display name.
Last active ago Last active ago
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
The server maintains a timestamp of the last time it saw a The server maintains a timestamp of the last time it saw a pro-active event from
pro-active event from the user. A pro-active event may be sending a message to a the user. A pro-active event may be sending a message to a room or changing
room or changing presence state to a higher level of availability. Levels of presence state to ``online``. This timestamp is presented via a key called
availability are defined from low to high as follows: ``last_active_ago`` which gives the relative number of milliseconds since the
pro-active event.
To reduce the number of presence updates sent to clients the server may include
a ``currently_active`` boolean field when the presence state is ``online``. When
true, the server will not send further updates to the last active time until an
update is sent to the client with either a) ``currently_active`` set to false or
b) a presence state other than ``online``. During this period clients must
consider the user to be currently active, irrespective of the last active time.
The last active time must be up to date whenever the server gives a presence
event to the client. The ``currently_active`` mechanism should purely be used by
servers to stop sending continuous presence updates, as opposed to disabling
last active tracking entirely. Thus clients can fetch up to date last active
times by explicitly requesting the presence for a given user.
- ``offline`` Idle timeout
- ``unavailable`` ~~~~~~~~~~~~
- ``online``
- ``free_for_chat``
Based on this list, changing state from ``unavailable`` to ``online`` counts as The server will automatically set a user's presence to ``unavailable`` if their
a pro-active event, whereas ``online`` to ``unavailable`` does not. This last active time was over a threshold value (e.g. 5 minutes). Clients can
timestamp is presented via a key called ``last_active_ago`` which gives the manually set a user's presence to ``unavailable``. Any activity that bumps the
relative number of milliseconds since the pro-active event. last active time on any of the user's clients will cause the server to
automatically set their presence to ``online``.
Security considerations Security considerations
----------------------- -----------------------
Presence information is shared with all users who share a room with the target Presence information is shared with all users who share a room with the target
user. In large public rooms this could be undesirable. user. In large public rooms this could be undesirable.

262
specification/modules/push.rst
Unescape Escape View File

@ -195,104 +195,274 @@ than "user-defined rules". The ``rule_id`` for all server-default rules MUST
start with a dot (".") to identify them as "server-default". The following start with a dot (".") to identify them as "server-default". The following
server-default rules are specified: server-default rules are specified:
``.m.rule.contains_user_name``
Matches any message whose content is unencrypted and contains the local part
of the user's Matrix ID, separated by word boundaries.
Definition (as a ``content`` rule):: Default Override Rules
^^^^^^^^^^^^^^^^^^^^^^
``m.rule.master``
`````````````````
Matches all events, this can be enabled to turn off all push notifications
other than those generated by override rules set by the user. By default this
rule is disabled.
Definition
.. code:: json
{ {
"rule_id": ".m.rule.contains_user_name" "rule_id": ".m.rule.master",
"pattern": "[the local part of the user's Matrix ID]", "default": true,
"enabled": false,
"conditions": [],
"actions": [ "actions": [
"notify", "dont_notify"
]
}
``.m.rule.suppress_notices``
````````````````````````````
Matches messages with a ``msgtype`` of ``notice``. This should be an
``override`` rule so that it takes priority over ``content`` / ``sender`` /
``room`` rules.
Definition:
.. code:: json
{
"rule_id": ".m.rule.suppress_notices",
"default": true,
"enabled": true,
"conditions": [
{ {
"set_tweak": "sound", "kind": "event_match",
"value": "default" "key": "content.msgtype",
"pattern": "m.notice",
} }
], ],
"actions": [
"dont_notify",
]
} }
``.m.rule.contains_display_name`` ``.m.rule.invite_for_me``
Matches any message whose content is unencrypted and contains the user's `````````````````````````
current display name in the room in which it was sent. Matches any invites to a new room for this user.
Definition:
Definition (this rule can only be an ``override`` or ``underride`` rule):: .. code:: json
{ {
"rule_id": ".m.rule.contains_display_name" "rule_id": ".m.rule.invite_for_me",
"default": true,
"enabled": true,
"conditions": [ "conditions": [
{ {
"kind": "contains_display_name" "key": "type",
"kind": "event_match",
"pattern": "m.room.member"
},
{
"key": "content.membership",
"kind": "event_match",
"pattern": "invite"
},
{
"key": "state_key",
"kind": "event_match",
"pattern": "[the user's Matrix ID]"
} }
], ],
"actions": [ "actions": [
"notify", "notify",
{ {
"set_tweak": "sound", "set_tweak": "sound",
"value": "default" "value": "default"
},
{
"set_tweak": "highlight",
"value": false
} }
], ]
} }
``.m.rule.room_one_to_one`` ``.m.rule.member_event``
Matches any message sent in a room with exactly two members. ````````````````````````
Definition (this rule can only be an ``override`` or ``underride`` rule):: Matches any ``m.room.member_event``.
Definition:
.. code:: json
{ {
"rule_id": ".m.rule.room_two_members" "rule_id": ".m.rule.member_event",
"default": true,
"enabled": true,
"conditions": [ "conditions": [
{ {
"is": "2", "key": "type",
"kind": "room_member_count" "kind": "event_match",
"pattern": "m.room.member"
} }
], ],
"actions": [
"dont_notify"
]
}
Default Content Rules
^^^^^^^^^^^^^^^^^^^^^
``.m.rule.contains_user_name``
``````````````````````````````
Matches any message whose content is unencrypted and contains the local part
of the user's Matrix ID, separated by word boundaries.
Definition (as a ``content`` rule):
.. code:: json
{
"rule_id": ".m.rule.contains_user_name",
"default": true,
"enabled": true,
"pattern": "[the local part of the user's Matrix ID]",
"actions": [ "actions": [
"notify", "notify",
{ {
"set_tweak": "sound", "set_tweak": "sound",
"value": "default" "value": "default"
} }
], ]
} }
``.m.rule.suppress_notices`` Default Underride Rules
Matches messages with a ``msgtype`` of ``notice``. This should be an ^^^^^^^^^^^^^^^^^^^^^^^
``override`` rule so that it takes priority over ``content`` / ``sender`` /
``room`` rules. ``.m.rule.call``
````````````````
Matches any incoming VOIP call.
Definition:
.. code:: json
{
"rule_id": ".m.rule.call",
"default": true,
"enabled": true,
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.call.invite"
}
],
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "ring"
},
{
"set_tweak": "highlight",
"value": false
}
]
},
``.m.rule.contains_display_name``
`````````````````````````````````
Matches any message whose content is unencrypted and contains the user's
current display name in the room in which it was sent.
Definition:
Definition:: .. code:: json
{ {
'rule_id': '.m.rule.suppress_notices', "rule_id": ".m.rule.contains_display_name",
'conditions': [ "default": true,
"enabled": true,
"conditions": [
{ {
'kind': 'event_match', "kind": "contains_display_name"
'key': 'content.msgtype',
'pattern': 'm.notice',
} }
], ],
'actions': [ "actions": [
'dont-notify', "notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
] ]
} }
``.m.rule.fallback``
Matches any message. Used to define the behaviour of messages that match no
other rules. If homeservers define this it should be the lowest priority
``underride`` rule.
Definition:: ``.m.rule.room_one_to_one``
```````````````````````````
Matches any message sent in a room with exactly two members.
Definition:
.. code:: json
{ {
"rule_id": ".m.rule.fallback" "rule_id": ".m.rule.room_one_to_one",
"conditions": [], "default": true,
"actions": [ "enabled": true,
"notify" "conditions": [
{
"kind": "room_member_count",
"is": "2"
}
], ],
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight",
"value": false
}
]
} }
``.m.rule.message``
```````````````````
Matches all chat messages.
Definition:
.. code:: json
{
"rule_id": ".m.rule.message",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.message"
}
],
"actions": [
"notify",
{
"set_tweak": "highlight",
"value": false
}
]
}
Conditions Conditions

2
specification/targets.yaml
Unescape Escape View File

@ -54,7 +54,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
- modules/event_context.rst - modules/event_context.rst
title_styles: ["=", "-", "~", "+", "^", "`", "@"] title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]
# The templating system doesn't know the right title style to use when generating # The templating system doesn't know the right title style to use when generating
# RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title # RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title

325
templating/matrix_templates/units.py
Unescape Escape View File

@ -14,6 +14,7 @@ import json
import os import os
import re import re
import subprocess import subprocess
import sys
import urllib import urllib
import yaml import yaml
@ -153,98 +154,121 @@ def get_json_schema_object_fields(obj, enforce_title=False,
required_keys = set(obj.get("required", [])) required_keys = set(obj.get("required", []))
fields = { obj_title = obj.get("title")
"title": obj.get("title"), first_table_rows = []
"rows": [] tables = []
}
tables = [fields]
for key_name in props: for key_name in props:
logger.debug("Processing property %s.%s", obj.get('title'), key_name) try:
prop = inherit_parents(props[key_name]) logger.debug("Processing property %s.%s", obj_title, key_name)
required = key_name in required_keys
res = process_prop(key_name, props[key_name], required,
mark_required)
first_table_rows.append(res["row"])
tables.extend(res["tables"])
logger.debug("Done property %s" % key_name)
except Exception, e:
e2 = Exception("Error reading property %s.%s: %s" %
(obj_title, key_name, str(e)))
# throw the new exception with the old stack trace, so that
# we don't lose information about where the error occurred.
raise e2, None, sys.exc_info()[2]
tables.insert(0, {
"title": obj_title,
"rows": first_table_rows,
})
value_type = None return tables
required = key_name in required_keys
desc = prop.get("description", "") def process_prop(key_name, prop, required, mark_required):
prop_type = prop.get('type') prop = inherit_parents(prop)
if prop_type is None: value_type = None
raise KeyError("Property '%s' of object '%s' missing 'type' field" desc = prop.get("description", "")
% (key_name, obj)) prop_type = prop.get('type')
logger.debug("%s is a %s", key_name, prop_type) tables = []
if prop_type == "object": if prop_type is None:
raise KeyError("Property '%s' of object '%s' missing 'type' field"
% (key_name, obj))
logger.debug("%s is a %s", key_name, prop_type)
if prop_type == "object":
nested_objects = get_json_schema_object_fields(
prop,
enforce_title=True,
mark_required=mark_required,
)
value_type = nested_objects[0]["title"]
value_id = value_type
tables += [x for x in nested_objects if not x.get("no-table")]
elif prop_type == "array":
items = inherit_parents(prop["items"])
# if the items of the array are objects then recurse
if items["type"] == "object":
nested_objects = get_json_schema_object_fields( nested_objects = get_json_schema_object_fields(
prop, items,
enforce_title=True, enforce_title=True,
mark_required=mark_required, mark_required=mark_required,
) )
value_type = nested_objects[0]["title"] value_id = nested_objects[0]["title"]
value_id = value_type value_type = "[%s]" % value_id
tables += nested_objects
tables += [x for x in nested_objects if not x.get("no-table")]
elif prop_type == "array":
items = inherit_parents(prop["items"])
# if the items of the array are objects then recurse
if items["type"] == "object":
nested_objects = get_json_schema_object_fields(
items,
enforce_title=True,
mark_required=mark_required,
)
value_id = nested_objects[0]["title"]
value_type = "[%s]" % value_id
tables += nested_objects
else:
value_type = items["type"]
if isinstance(value_type, list):
value_type = " or ".join(value_type)
value_id = value_type
value_type = "[%s]" % value_type
array_enums = items.get("enum")
if array_enums:
if len(array_enums) > 1:
value_type = "[enum]"
desc += (
" One of: %s" % json.dumps(array_enums)
)
else:
desc += (
" Must be '%s'." % array_enums[0]
)
else: else:
value_type = prop_type value_type = items["type"]
value_id = prop_type if isinstance(value_type, list):
if prop.get("enum"): value_type = " or ".join(value_type)
if len(prop["enum"]) > 1: value_id = value_type
value_type = "enum" value_type = "[%s]" % value_type
if desc: array_enums = items.get("enum")
desc += " " if array_enums:
if len(array_enums) > 1:
value_type = "[enum]"
desc += ( desc += (
"One of: %s" % json.dumps(prop["enum"]) " One of: %s" % json.dumps(array_enums)
) )
else: else:
if desc:
desc += " "
desc += ( desc += (
"Must be '%s'." % prop["enum"][0] " Must be '%s'." % array_enums[0]
) )
if isinstance(value_type, list): else:
value_type = " or ".join(value_type) value_type = prop_type
value_id = prop_type
if prop.get("enum"):
if len(prop["enum"]) > 1:
value_type = "enum"
if desc:
desc += " "
desc += (
"One of: %s" % json.dumps(prop["enum"])
)
else:
if desc:
desc += " "
desc += (
"Must be '%s'." % prop["enum"][0]
)
if isinstance(value_type, list):
value_type = " or ".join(value_type)
if required and mark_required: if required and mark_required:
desc = "**Required.** " + desc desc = "**Required.** " + desc
fields["rows"].append({
return {
"row": {
"key": key_name, "key": key_name,
"type": value_type, "type": value_type,
"id": value_id, "id": value_id,
"required": required, "required": required,
"desc": desc, "desc": desc,
}) },
logger.debug("Done property %s" % key_name) "tables": tables,
}
return tables
def get_tables_for_schema(schema, mark_required=True): def get_tables_for_schema(schema, mark_required=True):
@ -611,89 +635,102 @@ class MatrixUnits(Units):
if not filename.startswith("m."): if not filename.startswith("m."):
continue continue
filepath = os.path.join(path, filename) filepath = os.path.join(path, filename)
self.log("Reading %s" % filepath) try:
with open(filepath, "r") as f: schemata[filename] = self.read_event_schema(filepath)
json_schema = yaml.load(f) except Exception, e:
schema = { e2 = Exception("Error reading event schema "+filepath+": "+
"typeof": None, str(e))
"typeof_info": "", # throw the new exception with the old stack trace, so that
"type": None, # we don't lose information about where the error occurred.
"title": None, raise e2, None, sys.exc_info()[2]
"desc": None,
"msgtype": None,
"content_fields": [
# {
# title: "<title> key"
# rows: [
# { key: <key_name>, type: <string>,
# desc: <desc>, required: <bool> }
# ]
# }
]
}
# add typeof return schemata
base_defs = {
ROOM_EVENT: "Message Event",
STATE_EVENT: "State Event"
}
if type(json_schema.get("allOf")) == list:
schema["typeof"] = base_defs.get(
json_schema["allOf"][0].get("$ref")
)
elif json_schema.get("title"):
schema["typeof"] = json_schema["title"]
json_schema = resolve_references(filepath, json_schema) def read_event_schema(self, filepath):
self.log("Reading %s" % filepath)
with open(filepath, "r") as f:
json_schema = yaml.load(f)
schema = {
"typeof": None,
"typeof_info": "",
"type": None,
"title": None,
"desc": None,
"msgtype": None,
"content_fields": [
# {
# title: "<title> key"
# rows: [
# { key: <key_name>, type: <string>,
# desc: <desc>, required: <bool> }
# ]
# }
]
}
# add type # add typeof
schema["type"] = Units.prop( base_defs = {
json_schema, "properties/type/enum" ROOM_EVENT: "Message Event",
)[0] STATE_EVENT: "State Event"
}
if type(json_schema.get("allOf")) == list:
schema["typeof"] = base_defs.get(
json_schema["allOf"][0].get("$ref")
)
elif json_schema.get("title"):
schema["typeof"] = json_schema["title"]
# add summary and desc json_schema = resolve_references(filepath, json_schema)
schema["title"] = json_schema.get("title")
schema["desc"] = json_schema.get("description", "")
# walk the object for field info # add type
schema["content_fields"] = get_tables_for_schema( schema["type"] = Units.prop(
Units.prop(json_schema, "properties/content") json_schema, "properties/type/enum"
) )[0]
# This is horrible because we're special casing a key on m.room.member. # add summary and desc
# We need to do this because we want to document a non-content object. schema["title"] = json_schema.get("title")
if schema["type"] == "m.room.member": schema["desc"] = json_schema.get("description", "")
invite_room_state = get_tables_for_schema(
json_schema["properties"]["invite_room_state"]["items"],
)
schema["content_fields"].extend(invite_room_state)
# walk the object for field info
schema["content_fields"] = get_tables_for_schema(
Units.prop(json_schema, "properties/content")
)
# grab msgtype if it is the right kind of event # This is horrible because we're special casing a key on m.room.member.
msgtype = Units.prop( # We need to do this because we want to document a non-content object.
json_schema, "properties/content/properties/msgtype/enum" if schema["type"] == "m.room.member":
) invite_room_state = get_tables_for_schema(
if msgtype: json_schema["properties"]["invite_room_state"]["items"],
schema["msgtype"] = msgtype[0] # enum prop )
schema["content_fields"].extend(invite_room_state)
# link to msgtypes for m.room.message
if schema["type"] == "m.room.message" and not msgtype:
schema["desc"] += (
" For more information on ``msgtypes``, see "+
"`m.room.message msgtypes`_."
)
# Assign state key info if it has some
if schema["typeof"] == "State Event":
skey_desc = Units.prop(
json_schema, "properties/state_key/description"
)
if not skey_desc:
raise Exception("Missing description for state_key")
schema["typeof_info"] = "``state_key``: %s" % skey_desc
schemata[filename] = schema # grab msgtype if it is the right kind of event
return schemata msgtype = Units.prop(
json_schema, "properties/content/properties/msgtype/enum"
)
if msgtype:
schema["msgtype"] = msgtype[0] # enum prop
# link to msgtypes for m.room.message
if schema["type"] == "m.room.message" and not msgtype:
schema["desc"] += (
" For more information on ``msgtypes``, see "+
"`m.room.message msgtypes`_."
)
# Assign state key info if it has some
if schema["typeof"] == "State Event":
skey_desc = Units.prop(
json_schema, "properties/state_key/description"
)
if not skey_desc:
raise Exception("Missing description for state_key")
schema["typeof_info"] = "``state_key``: %s" % skey_desc
return schema
def load_changelogs(self): def load_changelogs(self):
changelogs = {} changelogs = {}

Write Preview
Loading…
Cancel
Save