From 03b8c7a12b0ce16bb6b720ba556b6ca78c3fc5a5 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Fri, 4 Sep 2015 11:43:11 +0100
Subject: [PATCH] Document the canonical alias event

---
 .../examples/v1/m.room.canonical_alias        | 12 ++++++++
 .../schema/v1/m.room.canonical_alias          | 30 +++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 event-schemas/examples/v1/m.room.canonical_alias
 create mode 100644 event-schemas/schema/v1/m.room.canonical_alias

diff --git a/event-schemas/examples/v1/m.room.canonical_alias b/event-schemas/examples/v1/m.room.canonical_alias
new file mode 100644
index 00000000..9fd170d9
--- /dev/null
+++ b/event-schemas/examples/v1/m.room.canonical_alias
@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "alias": "#somewhere:localhost"
+  },
+  "state_key": "",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.aliases",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}
diff --git a/event-schemas/schema/v1/m.room.canonical_alias b/event-schemas/schema/v1/m.room.canonical_alias
new file mode 100644
index 00000000..bca91aa7
--- /dev/null
+++ b/event-schemas/schema/v1/m.room.canonical_alias
@@ -0,0 +1,30 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "title": "Informs the room as to which alias is the canonical one.",
+    "description": "This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.",
+    "allOf": [{
+        "$ref": "core#/definitions/state_event"
+    }],
+    "properties": {
+        "content": {
+            "type": "object",
+            "properties": {
+                "alias": {
+                    "type": "String",
+                    "description": "The canonical alias.",
+                }
+            },
+            "required": ["alias"]
+        },
+        "state_key": {
+            "type": "string",
+            "description": "A zero-length string.",
+            "pattern": "^$"
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.room.canonical_alias"]
+        }
+    }
+}