Sticker messages (m.sticker) (#1158)

changelogs/client_server.rst

@@ -10,8 +10,16 @@ Unreleased changes
     - ``GET /rooms/{roomId}/event/{eventId}``
       (`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
 
+  - Sticker messages:
+    - Add sticker message event definition.
+    (`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
+
 - Spec clarifications:
 
+  - Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions
+    to clarify that they relate to intended display size, as opposed to the
+    intrinsic size of the image file.
+    (`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
   - Mark ``home_server`` return field for ``/login`` and ``/register``
     endpoints as deprecated
     (`#1097 <https://github.com/matrix-org/matrix-doc/pull/1097>`_).

event-schemas/examples/m.sticker

@@ -0,0 +1,25 @@
+{
+  "age": 242352,
+  "content": {
+    "body": "Landing",
+    "info": {
+      "mimetype": "image/png",
+      "thumbnail_info": {
+        "mimetype": "image/png",
+        "h": 200,
+        "w": 140,
+        "size": 73602
+      },
+      "h": 200,
+      "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP",
+      "w": 140,
+      "size": 73602
+    },
+    "url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP"
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.sticker",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "sender": "@example:localhost"
+}

event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml

@@ -2,10 +2,14 @@ $schema: http://json-schema.org/draft-04/schema#
 description: Metadata about an image.
 properties:
   h:
-    description: The height of the image in pixels.
+    description: |-
+      The intended display height of the image in pixels. This may
+      differ from the intrinsic dimensions of the image file.
     type: integer
   w:
-    description: The width of the image in pixels.
+    description: |-
+      The intended display width of the image in pixels. This may
+      differ from the intrinsic dimensions of the image file.
     type: integer
   mimetype:
     description: The mimetype of the image, e.g. ``image/jpeg``.

event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml

@@ -2,10 +2,14 @@ $schema: http://json-schema.org/draft-04/schema#
 description: Metadata about a thumbnail image.
 properties:
   h:
-    description: The height of the image in pixels.
+    description: |-
+      The intended display height of the image in pixels. This may
+      differ from the intrinsic dimensions of the image file.
     type: integer
   w:
-    description: The width of the image in pixels.
+    description: |-
+      The intended display width of the image in pixels. This may
+      differ from the intrinsic dimensions of the image file.
     type: integer
   mimetype:
     description: The mimetype of the image, e.g. ``image/jpeg``.

event-schemas/schema/m.sticker

@@ -0,0 +1,34 @@
+---
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: This message represents a single sticker image.
+properties:
+  content:
+    properties:
+      body:
+        description: |-
+          A textual representation or associated description of the sticker
+          image. This could be the alt text of the original image, or a message
+          to accompany and further describe the sticker.
+        type: string
+      info:
+        allOf:
+          - $ref: core-event-schema/msgtype_infos/image_info.yaml
+        description: |-
+          Metadata about the image referred to in ``url`` including a thumbnail
+          representation.
+      url:
+        description: |-
+          The URL to the sticker image. This must be a valid ``mxc://`` URI.
+        type: string
+    required:
+      - body
+      - info
+      - url
+    type: object
+  type:
+    enum:
+      - m.sticker
+    type: string
+title: StickerMessage
+type: object

specification/modules/stickers.rst

@@ -0,0 +1,53 @@
+.. Copyright 2018 New Vector Ltd.
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Sticker Messages
+================
+
+.. _module:stickers:
+
+This module allows users to send sticker messages in to rooms or direct
+messaging sessions.
+
+Sticker messages are specialised image messages that are displayed without
+controls (e.g. no "download" link, or light-box view on click, as would be
+displayed for for `m.image`_ events).
+
+Sticker messages are intended to provide simple "reaction" events in the message
+timeline. The matrix client should provide some mechanism to display the sticker
+"body" e.g. as a tooltip on hover, or in a modal when the sticker image is
+clicked.
+
+Events
+------
+Sticker events are received as a single ``m.sticker`` event in the
+``timeline`` section of a room, in a ``/sync``.
+
+{{m_sticker_event}}
+
+Client behaviour
+----------------
+
+Clients supporting this message type should display the image content from the
+event URL directly in the timeline.
+
+A thumbnail image should be provided in the ``info`` object. This is
+largely intended as a fallback for clients that do not fully support the
+``m.sticker`` event type. In most cases it is fine to set the thumbnail URL to the
+same URL as the main event content.
+
+It is recommended that sticker image content should be 512x512 pixels in size
+or smaller. The dimensions of the image file should be twice the intended
+display size specified in the ``info`` object in order to assist
+rendering sharp images on higher DPI screens.

specification/targets.yaml

@@ -62,6 +62,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/cas_login.rst
     - modules/dm.rst
     - modules/ignore_users.rst
+    - modules/stickers.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]