wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #27 from matrix-org/receipts

Browse source 
Document receipts
This commit is contained in:
Kegsay 2015-09-10 16:18:19 +01:00
commit 3011823c51
4 changed files with 138 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

13
event-schemas/examples/v1/m.receipt Normal file
View file

@ -0,0 +1,13 @@
{
"type": "m.receipt",
"room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org",
"content": {
"$1435641916114394fHBLK:matrix.org": {
"read": {
"@rikj:jki.re": {
"ts": 1436451550453
}
}
}
}
}

43
event-schemas/schema/v1/m.receipt Normal file
View file

@ -0,0 +1,43 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Receipt Event",
"description": "Informs the client of new receipts.",
"properties": {
"content": {
"type": "object",
"description": "The event ids which the receipts relate to.",
"patternProperties": {
"^\\$": {
"type": "object",
"description": "The types of the receipts.",
"additionalProperties": {
"type": "object",
"description": "User ids of the receipts",
"patternProperties": {
"^@": {
"type": "object",
"properties": {
"ts": {
"type": "number",
"description": "The timestamp the receipt was sent at"
}
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"type": {
"type": "string",
"enum": ["m.receipt"]
},
"room_id": {
"type": "string"
}
},
"required": ["room_id", "type", "content"]
}

81
specification/46_receipts.rst Normal file
View file

@ -0,0 +1,81 @@
Receipts
========
Receipts are used to publish which events in a room the user or their devices
have interacted with. For example, which events the user has read.
For efficiency this is done as "up to" markers, i.e. marking a particular event
as, say, ``read`` indicates the user has read all events *up to* that event.
Client-Server API
-----------------
Clients will receive receipts in the following format::
{
"type": "m.receipt",
"room_id": <room_id>,
"content": {
<event_id>: {
<receipt_type>: {
<user_id>: { "ts": <ts>, ... },
...
}
},
...
}
}
For example::
{
"type": "m.receipt",
"room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org",
"content": {
"$1435641916114394fHBLK:matrix.org": {
"read": {
"@erikj:jki.re": { "ts": 1436451550453 },
...
}
},
...
}
}
For efficiency, receipts are batched into one event per room. In the initialSync
and v2 sync APIs the receipts are listed in a seperate top level ``receipts``
key.
Each ``user_id``, ``receipt_type`` pair must be associated with only a single
``event_id``.
New receipts that come down the event streams are deltas. Deltas update
existing mappings, clobbering based on ``user_id``, ``receipt_type`` pairs.
A client can update the markers for its user by issuing a request::
POST /_matrix/client/v2_alpha/rooms/<room_id>/receipt/read/<event_id>
Where the contents of the ``POST`` will be included in the content sent to
other users. The server will automatically set the ``ts`` field.
Server-Server API
-----------------
Receipts are sent across federation as EDUs with type ``m.receipt``. The
format of the EDUs are::
{
<room_id>: {
<receipt_type>: {
<user_id>: { <content> }
},
...
},
...
}
These are always sent as deltas to previously sent reciepts.

2
templating/matrix_templates/units.py
View file

@ -30,7 +30,7 @@ def get_json_schema_object_fields(obj, enforce_title=False):
}
tables = [fields]
props = obj.get("properties")
props = obj.get("properties", obj.get("patternProperties"))
parents = obj.get("allOf")
if not props and not parents:
raise Exception(