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

Add descriptions to event fields

Browse Source
pull/977/head
Kegan Dougal 10 years ago
parent 989ea02219
commit 6a41bd9b82
11 changed files with 65 additions and 26 deletions
Show Stats Download Patch File Download Diff File

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

@ -6,20 +6,25 @@
"type": "object", "type": "object",
"properties": { "properties": {
"avatar_url": { "avatar_url": {
"type": "string" "type": "string",
"description": "The current avatar URL for this user, if any."
}, },
"displayname": { "displayname": {
"type": "string" "type": "string",
"description": "The current display name for this user, if any."
}, },
"last_active_ago": { "last_active_ago": {
"type": "number" "type": "number",
"description": "The last time since this used performed some action, in milliseconds."
}, },
"presence": { "presence": {
"type": "string", "type": "string",
"description": "The presence state for this user.",
"enum": ["online", "offline", "unavailable", "free_for_chat", "hidden"] "enum": ["online", "offline", "unavailable", "free_for_chat", "hidden"]
}, },
"user_id": { "user_id": {
"type": "string" "type": "string",
"description": "The user's ID."
} }
}, },
"required": ["presence", "user_id"] "required": ["presence", "user_id"]

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

@ -12,6 +12,7 @@
"properties": { "properties": {
"aliases": { "aliases": {
"type": "array", "type": "array",
"description": "A list of room aliases.",
"items": { "items": {
"type": "string" "type": "string"
} }

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

@ -11,7 +11,8 @@
"type": "object", "type": "object",
"properties": { "properties": {
"creator": { "creator": {
"type": "string" "type": "string",
"description": "The ``user_id`` of the room creator. This is set by the homeserver."
} }
}, },
"required": ["creator"] "required": ["creator"]

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

@ -12,6 +12,7 @@
"properties": { "properties": {
"join_rule": { "join_rule": {
"type": "string", "type": "string",
"description": "The type of rules used for users wishing to join this room.",
"enum": ["public","knock","invite","private"] "enum": ["public","knock","invite","private"]
} }
}, },

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

@ -12,13 +12,16 @@
"properties": { "properties": {
"membership": { "membership": {
"type": "string", "type": "string",
"description": "The membership state of the user.",
"enum": ["invite","join","knock","leave","ban"] "enum": ["invite","join","knock","leave","ban"]
}, },
"avatar_url": { "avatar_url": {
"type": "string" "type": "string",
"description": "The avatar URL for this user, if any. This is added by the homeserver."
}, },
"displayname": { "displayname": {
"type": "string" "type": "string",
"description": "The display name for this user, if any. This is added by the homeserver."
} }
}, },
"required": ["membership"] "required": ["membership"]

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

@ -1,7 +1,7 @@
{ {
"$schema": "http://json-schema.org/draft-04/schema#", "$schema": "http://json-schema.org/draft-04/schema#",
"type": "object", "type": "object",
"title": "A human-readable message in the room.", "title": "Message",
"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.", "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.",
"allOf": [{ "allOf": [{
"$ref": "core#/definitions/room_event" "$ref": "core#/definitions/room_event"
@ -11,10 +11,12 @@
"type": "object", "type": "object",
"properties": { "properties": {
"msgtype": { "msgtype": {
"type": "string" "type": "string",
"description": "The type of message, e.g. ``m.image``, ``m.text``"
}, },
"body": { "body": {
"type": "string" "type": "string",
"description": "The textual representation of this message."
} }
}, },
"required": ["msgtype", "body"] "required": ["msgtype", "body"]

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

@ -1,8 +1,8 @@
{ {
"$schema": "http://json-schema.org/draft-04/schema#", "$schema": "http://json-schema.org/draft-04/schema#",
"type": "object", "type": "object",
"title": "A receipt for a message. N.B. not implemented in Synapse, and superceded in v2 CS API by the ``relates_to`` event field.", "title": "MessageFeedback",
"description": "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": "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. N.B. not implemented in Synapse, and superceded in v2 CS API by the ``relates_to`` event field.",
"allOf": [{ "allOf": [{
"$ref": "core#/definitions/room_event" "$ref": "core#/definitions/room_event"
}], }],
@ -12,10 +12,12 @@
"properties": { "properties": {
"type": { "type": {
"type": "string", "type": "string",
"description": "The type of feedback.",
"enum": ["delivered", "read"] "enum": ["delivered", "read"]
}, },
"target_event_id": { "target_event_id": {
"type": "string" "type": "string",
"description": "The event that this feedback is related to."
} }
}, },
"required": ["type", "target_event_id"] "required": ["type", "target_event_id"]

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

@ -1,6 +1,6 @@
{ {
"$schema": "http://json-schema.org/draft-04/schema#", "$schema": "http://json-schema.org/draft-04/schema#",
"title": "Set the human-readable name for the room.", "title": "RoomName",
"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.", "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.",
"type": "object", "type": "object",
"allOf": [{ "allOf": [{
@ -11,7 +11,8 @@
"type": "object", "type": "object",
"properties": { "properties": {
"name": { "name": {
"type": "string" "type": "string",
"description": "The name of the room."
} }
}, },
"required": ["name"] "required": ["name"]

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

@ -10,15 +10,34 @@
"content": { "content": {
"type": "object", "type": "object",
"properties": { "properties": {
"ban": { "type": "number" }, "ban": {
"events_default": { "type": "number" }, "type": "number",
"kick": { "type": "number" }, "description": "The level required to ban a user."
"redact": { "type": "number" }, },
"state_default": { "type": "number" }, "events_default": {
"users_default": { "type": "number" }, "type": "number",
"description": "The default level required to send message events. Can be overidden by the ``events`` key."
},
"kick": {
"type": "number",
"description": "The level required to kick a user."
},
"redact": {
"type": "number",
"description": "The level required to redact an event."
},
"state_default": {
"type": "number",
"description": "The default level required to send state events. Can be overriden by the ``events`` key."
},
"users_default": {
"type": "number",
"description": "The default power level for every user in the room, unless their ``user_id`` is mentioned in the ``users`` key."
},
"events": { "events": {
"type": "object", "type": "object",
"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.",
"additionalProperties": { "additionalProperties": {
"type": "number" "type": "number"
} }
@ -26,6 +45,7 @@
"users": { "users": {
"type": "object", "type": "object",
"title": "User power levels", "title": "User power levels",
"description": "The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.",
"additionalProperties": { "additionalProperties": {
"type": "number" "type": "number"
} }

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

@ -1,7 +1,7 @@
{ {
"$schema": "http://json-schema.org/draft-04/schema#", "$schema": "http://json-schema.org/draft-04/schema#",
"type": "object", "type": "object",
"title": "Indicates a previous event has been redacted.", "title": "Redaction",
"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": [{ "allOf": [{
"$ref": "core#/definitions/room_event" "$ref": "core#/definitions/room_event"
@ -11,12 +11,14 @@
"type": "object", "type": "object",
"properties": { "properties": {
"reason": { "reason": {
"type": "string" "type": "string",
"description": "The reason for the redaction, if any."
} }
} }
}, },
"redacts": { "redacts": {
"type": "string" "type": "string",
"description": "The event ID that was redacted."
}, },
"type": { "type": {
"type": "string", "type": "string",

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

@ -1,7 +1,7 @@
{ {
"$schema": "http://json-schema.org/draft-04/schema#", "$schema": "http://json-schema.org/draft-04/schema#",
"type": "object", "type": "object",
"title": "Set a topic for the room.", "title": "Topic",
"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": [{ "allOf": [{
"$ref": "core#/definitions/state_event" "$ref": "core#/definitions/state_event"
@ -11,7 +11,8 @@
"type": "object", "type": "object",
"properties": { "properties": {
"topic": { "topic": {
"type": "string" "type": "string",
"description": "The topic text."
} }
}, },
"required": ["topic"] "required": ["topic"]

Write Preview
Loading…
Cancel
Save