From e03bfbc47b5079a7bd54bbce1a4996524b6fc617 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Fri, 3 Aug 2018 22:52:33 -0600
Subject: [PATCH] Document how read receipts work over federation

Federation format: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/receipts.py#L153-L166

Population of the fields that the above uses to construct the EDU: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/receipts.py#L48-L56
---
 .../definitions/event-schemas/m.receipt.yaml  | 82 +++++++++++++++++++
 specification/server_server_api.rst           | 12 +++
 2 files changed, 94 insertions(+)
 create mode 100644 api/server-server/definitions/event-schemas/m.receipt.yaml

diff --git a/api/server-server/definitions/event-schemas/m.receipt.yaml b/api/server-server/definitions/event-schemas/m.receipt.yaml
new file mode 100644
index 000000000..b8638427e
--- /dev/null
+++ b/api/server-server/definitions/event-schemas/m.receipt.yaml
@@ -0,0 +1,82 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: Receipt EDU
+description: |-
+  An EDU representing receipt updates for users of the sending homeserver.
+  When receiving receipts, the server should only update entries that are
+  listed in the EDU. Receipts previously received that do not appear in the
+  EDU should not be removed or otherwise manipulated.
+allOf:
+  - $ref: ../edu.yaml
+  - type: object
+    properties:
+      edu_type:
+        type: string
+        description: The string ``m.receipt``
+        example: "m.receipt"
+      content:
+        type: object
+        description: |-
+          Receipts for a particular room. The string key is the room ID for
+          which the receipts under it belong.
+        additionalProperties:
+          type: object
+          title: Room Receipts
+          properties:
+            # We strongly define the receipt type to help spec future ones later
+            # on. At that point, m.read can become optional (maybe).
+            "m.read":
+              type: object
+              description: Read receipts for users in the room.
+              title: User Read Receipt
+              properties:
+                event_ids:
+                  type: array
+                  description: |-
+                    The event ID that the user has read up to. Must be exactly
+                    one element in length.
+                  minItems: 1
+                  maxItems: 1
+                  items:
+                    type: string
+                  example: ['$read_this_event:matrix.org']
+                data:
+                  type: object
+                  description: Metadata for the read receipt.
+                  title: Read Receipt Metadata
+                  properties:
+                    ts:
+                      type: integer
+                      format: int64
+                      description: |-
+                        A POSIX timestamp in milliseconds for when the user read
+                        the event specified in the read receipt.
+                      example: 1533358089009
+                  required: ['ts']
+              required: ['event_ids', 'data']
+          required: ['m.read']
+        example: {
+          "!some_room:domain.com": {
+            "m.read": {
+              "@john:matrix.org": {
+                "event_ids": ["$read_this_event:matrix.org"],
+                "data": {
+                  "ts": 1533358089009
+                }
+              }
+            }
+          }
+        }
diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst
index a3d3f83aa..f19f41a61 100644
--- a/specification/server_server_api.rst
+++ b/specification/server_server_api.rst
@@ -896,6 +896,18 @@ Rejecting a presence invite::
   - Explain the zero-byte presence inference logic
   See also: docs/client-server/model/presence
 
+Receipts
+--------
+
+Receipts are EDUs used to communicate a marker for a given event. Currently the
+only kind of receipt supported is a "read receipt", or where in the timeline a
+user has read up to.
+
+Read receipts for events events that a user sent do not need to be sent. It is
+implied that by sending the event the user has read up to the event.
+
+{{definition_ss_event_schemas_m_receipt}}
+
 Querying for information
 ------------------------