From 6a41bd9b82c990d1dd668bd77b97e53ac5577c2a Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 21 May 2015 12:02:07 +0100 Subject: [PATCH] Add descriptions to event fields --- event-schemas/schema/v1/m.presence | 13 +++++--- event-schemas/schema/v1/m.room.aliases | 1 + event-schemas/schema/v1/m.room.create | 3 +- event-schemas/schema/v1/m.room.join_rules | 1 + event-schemas/schema/v1/m.room.member | 7 ++-- event-schemas/schema/v1/m.room.message | 8 +++-- .../schema/v1/m.room.message.feedback | 8 +++-- event-schemas/schema/v1/m.room.name | 5 +-- event-schemas/schema/v1/m.room.power_levels | 32 +++++++++++++++---- event-schemas/schema/v1/m.room.redaction | 8 +++-- event-schemas/schema/v1/m.room.topic | 5 +-- 11 files changed, 65 insertions(+), 26 deletions(-) diff --git a/event-schemas/schema/v1/m.presence b/event-schemas/schema/v1/m.presence index 815c6af98..f7cc60480 100644 --- a/event-schemas/schema/v1/m.presence +++ b/event-schemas/schema/v1/m.presence @@ -6,20 +6,25 @@ "type": "object", "properties": { "avatar_url": { - "type": "string" + "type": "string", + "description": "The current avatar URL for this user, if any." }, "displayname": { - "type": "string" + "type": "string", + "description": "The current display name for this user, if any." }, "last_active_ago": { - "type": "number" + "type": "number", + "description": "The last time since this used performed some action, in milliseconds." }, "presence": { "type": "string", + "description": "The presence state for this user.", "enum": ["online", "offline", "unavailable", "free_for_chat", "hidden"] }, "user_id": { - "type": "string" + "type": "string", + "description": "The user's ID." } }, "required": ["presence", "user_id"] diff --git a/event-schemas/schema/v1/m.room.aliases b/event-schemas/schema/v1/m.room.aliases index 03842221b..6bfa50f86 100644 --- a/event-schemas/schema/v1/m.room.aliases +++ b/event-schemas/schema/v1/m.room.aliases @@ -12,6 +12,7 @@ "properties": { "aliases": { "type": "array", + "description": "A list of room aliases.", "items": { "type": "string" } diff --git a/event-schemas/schema/v1/m.room.create b/event-schemas/schema/v1/m.room.create index 53bb1a45f..f133124ad 100644 --- a/event-schemas/schema/v1/m.room.create +++ b/event-schemas/schema/v1/m.room.create @@ -11,7 +11,8 @@ "type": "object", "properties": { "creator": { - "type": "string" + "type": "string", + "description": "The ``user_id`` of the room creator. This is set by the homeserver." } }, "required": ["creator"] diff --git a/event-schemas/schema/v1/m.room.join_rules b/event-schemas/schema/v1/m.room.join_rules index 7c8189b2c..16f5c9a68 100644 --- a/event-schemas/schema/v1/m.room.join_rules +++ b/event-schemas/schema/v1/m.room.join_rules @@ -12,6 +12,7 @@ "properties": { "join_rule": { "type": "string", + "description": "The type of rules used for users wishing to join this room.", "enum": ["public","knock","invite","private"] } }, diff --git a/event-schemas/schema/v1/m.room.member b/event-schemas/schema/v1/m.room.member index 5cd8d297d..a14a6c91b 100644 --- a/event-schemas/schema/v1/m.room.member +++ b/event-schemas/schema/v1/m.room.member @@ -12,13 +12,16 @@ "properties": { "membership": { "type": "string", + "description": "The membership state of the user.", "enum": ["invite","join","knock","leave","ban"] }, "avatar_url": { - "type": "string" + "type": "string", + "description": "The avatar URL for this user, if any. This is added by the homeserver." }, "displayname": { - "type": "string" + "type": "string", + "description": "The display name for this user, if any. This is added by the homeserver." } }, "required": ["membership"] diff --git a/event-schemas/schema/v1/m.room.message b/event-schemas/schema/v1/m.room.message index e5a109f7f..a849f07f5 100644 --- a/event-schemas/schema/v1/m.room.message +++ b/event-schemas/schema/v1/m.room.message @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "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.", "allOf": [{ "$ref": "core#/definitions/room_event" @@ -11,10 +11,12 @@ "type": "object", "properties": { "msgtype": { - "type": "string" + "type": "string", + "description": "The type of message, e.g. ``m.image``, ``m.text``" }, "body": { - "type": "string" + "type": "string", + "description": "The textual representation of this message." } }, "required": ["msgtype", "body"] diff --git a/event-schemas/schema/v1/m.room.message.feedback b/event-schemas/schema/v1/m.room.message.feedback index 62c75e325..4cfd44d1e 100644 --- a/event-schemas/schema/v1/m.room.message.feedback +++ b/event-schemas/schema/v1/m.room.message.feedback @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "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.", - "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.", + "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. N.B. not implemented in Synapse, and superceded in v2 CS API by the ``relates_to`` event field.", "allOf": [{ "$ref": "core#/definitions/room_event" }], @@ -12,10 +12,12 @@ "properties": { "type": { "type": "string", + "description": "The type of feedback.", "enum": ["delivered", "read"] }, "target_event_id": { - "type": "string" + "type": "string", + "description": "The event that this feedback is related to." } }, "required": ["type", "target_event_id"] diff --git a/event-schemas/schema/v1/m.room.name b/event-schemas/schema/v1/m.room.name index 3d70fa166..ba990c61e 100644 --- a/event-schemas/schema/v1/m.room.name +++ b/event-schemas/schema/v1/m.room.name @@ -1,6 +1,6 @@ { "$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.", "type": "object", "allOf": [{ @@ -11,7 +11,8 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the room." } }, "required": ["name"] diff --git a/event-schemas/schema/v1/m.room.power_levels b/event-schemas/schema/v1/m.room.power_levels index 6e4250250..d439e4a08 100644 --- a/event-schemas/schema/v1/m.room.power_levels +++ b/event-schemas/schema/v1/m.room.power_levels @@ -10,15 +10,34 @@ "content": { "type": "object", "properties": { - "ban": { "type": "number" }, - "events_default": { "type": "number" }, - "kick": { "type": "number" }, - "redact": { "type": "number" }, - "state_default": { "type": "number" }, - "users_default": { "type": "number" }, + "ban": { + "type": "number", + "description": "The level required to ban a user." + }, + "events_default": { + "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": { "type": "object", "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": { "type": "number" } @@ -26,6 +45,7 @@ "users": { "type": "object", "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": { "type": "number" } diff --git a/event-schemas/schema/v1/m.room.redaction b/event-schemas/schema/v1/m.room.redaction index fb6dd9972..2896c0da4 100644 --- a/event-schemas/schema/v1/m.room.redaction +++ b/event-schemas/schema/v1/m.room.redaction @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "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.", "allOf": [{ "$ref": "core#/definitions/room_event" @@ -11,12 +11,14 @@ "type": "object", "properties": { "reason": { - "type": "string" + "type": "string", + "description": "The reason for the redaction, if any." } } }, "redacts": { - "type": "string" + "type": "string", + "description": "The event ID that was redacted." }, "type": { "type": "string", diff --git a/event-schemas/schema/v1/m.room.topic b/event-schemas/schema/v1/m.room.topic index b3fc4574d..4849b229c 100644 --- a/event-schemas/schema/v1/m.room.topic +++ b/event-schemas/schema/v1/m.room.topic @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "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.", "allOf": [{ "$ref": "core#/definitions/state_event" @@ -11,7 +11,8 @@ "type": "object", "properties": { "topic": { - "type": "string" + "type": "string", + "description": "The topic text." } }, "required": ["topic"]