Merge remote-tracking branch 'origin/develop' into develop

1 files changed, 33 insertions, 0 deletions

diff --git a/docs/specification.rst b/docs/specification.rst

index e9e9296073..23b6bed764 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -1127,6 +1127,23 @@ There are several APIs provided to ``GET`` events for a room:
   Example:
     TODO
 
+Redactions
+----------
+Since events are extensible it is possible for malicious users and/or servers to add
+keys that are, for example offensive or illegal. Since some events cannot be simply
+deleted, e.g. membership events, we instead 'redact' events. This involves removing
+all keys from an event that are not required by the protocol. This stripped down
+event is thereafter returned anytime a client or remote server requests it.
+
+Events that have been redacted include a ``redacted_because`` key whose value is the
+event that caused it to be redacted, which may include a reason.
+
+Redacting an event cannot be undone, allowing server owners to delete the offending
+content from the databases.
+
+Currently, only room admins can redact events by sending a ``m.room.redacted`` event,
+but server admins also need to be able to redact events by a similar mechanism.
+
 
 Room Events
 ===========
@@ -1321,6 +1338,22 @@ prefixed with ``m.``
     end-user). The ``target_event_id`` should reference the ``m.room.message``
     event being acknowledged. 
 
+``m.room.redaction``
+  Summary:
+    Indicates a previous event has been redacted.
+  Type:
+    Non-state event
+  JSON format:
+    ``{ "reason": "string" }``
+  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 non-state 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.
+
 m.room.message msgtypes
 -----------------------
 Each ``m.room.message`` MUST have a ``msgtype`` key which identifies the type