diff --git a/README.md b/README.md
index 1f23bb6..94d8a7f 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,32 @@ This includes context-dependent hints and the automatic typing of commands to a
 
 Note that our frontend implementation is written in Angular. It is maintained and documented in the `frontend-tutorial-framework` repository.
 
+### Messaging format
+
+The framework uses JSON messages internally and in exposed APIs as well.
+These messages must comply some rules.
+Don't worry, we are not too fond of rules around these parts.
+
+The TFW message format:
+
+```json
+{
+    "key: "some identifier used for addressing",
+    "data":
+    {
+        ...
+        JSON object carrying anything, preferably cats
+        ...
+    },
+    "trigger": "FSM action"
+}
+```
+
+- The `key` field is used by TFW for addressing and every message must have one (it can be an empty string though)
+- The `data` object can contain anything you might want to send
+- The `trigger` key is an optional field that triggers an FSM action with that name from the current state (whatever that might be)
+
+
 ## Where to go next
 
 Most of the components you need have docstrings included (hang on tight, this is work in progress) – refer to them for usage info.