Fix inconsistencies regarding redacted_because

Signed-off-by: Benjamin Saunders <ben.e.saunders@gmail.com>

api/client-server/definitions/event.yaml

@@ -52,6 +52,10 @@ properties:
           This key will only be present for message events sent by the device calling
           this API.
         type: string
+      redacted_because:
+        description: Optional. The event that redacted this event, if any.
+        title: Event
+        type: object
     title: Unsigned
     type: object
 title: Event

changelogs/client_server.rst

@@ -21,6 +21,8 @@
     (`#371 <https://github.com/matrix-org/matrix-doc/pull/371>`_).
   - Correct references to ``user_id`` which should have been ``sender``
     (`#376 <https://github.com/matrix-org/matrix-doc/pull/376>`_).
+  - Correct inconsistent specification of ``redacted_because`` fields and their
+    values (`#378 <https://github.com/matrix-org/matrix-doc/pull/378>`_).
 
 - Changes to the API which will be backwards-compatible for clients:
 

event-schemas/examples/m.room.redaction

@@ -1,5 +1,7 @@
 {
-  "age": 242352,
+  "unsigned": {
+    "age": 242352
+  },
   "content": {
     "reason": "Spamming"
   },

event-schemas/schema/core-event-schema/room_event.yaml

@@ -25,8 +25,9 @@ properties:
           sent
         type: integer
       redacted_because:
-        description: The reason this event was redacted, if it was redacted
-        type: string
+        description: Optional. The event that redacted this event, if any.
+        title: Event
+        type: object
       transaction_id:
         description: The client-supplied transaction ID, if the client being given
           the event is the same one which sent it.

specification/client_server_api.rst

@@ -970,9 +970,10 @@ one of the following event types:
   ``kick``, ``redact``, ``state_default``, ``users``, ``users_default``.
 - ``m.room.aliases`` allows key ``aliases``
 
-The redaction event should be added under the key ``redacted_because``. When a
-client receives a redaction event it should change the redacted event
-in the same way a server does.
+The server should add the event causing the redaction to the ``unsigned``
+property of the redacted event, under the ``redacted_because`` key. When a
+client receives a redaction event it should change the redacted event in the
+same way a server does.
 
 Events
 ++++++