From 52f55e05422024e6701b8d211258e1b6a4011a00 Mon Sep 17 00:00:00 2001
From: Mark Haines <mark.haines@matrix.org>
Date: Mon, 2 Nov 2015 13:31:25 +0000
Subject: [PATCH] Allow room tags to have asssociated content, and return that
 content in the m.tag events

---
 api/client-server/v2_alpha/tags.yaml | 17 ++++++++---------
 event-schemas/examples/v1/m.tag      |  6 +++---
 event-schemas/schema/v1/m.tag        |  7 ++++---
 specification/modules/tags.rst       |  3 +++
 4 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/api/client-server/v2_alpha/tags.yaml b/api/client-server/v2_alpha/tags.yaml
index 91b812124..009e6000c 100644
--- a/api/client-server/v2_alpha/tags.yaml
+++ b/api/client-server/v2_alpha/tags.yaml
@@ -49,16 +49,15 @@ paths:
             type: object
             properties:
               tags:
-                type: array
-                items:
-                  type: string
+                title: Tags
+                type: object
           examples:
             application/json: |-
               {
-                "tags": [
-                  "work",
-                  "pinned"
-                ]
+                "tags": {
+                  "work": {"order": 1},
+                  "pinned": {}
+                }
               }
   "/user/{userId}/rooms/{roomId}/tags/{tag}":
     put:
@@ -94,11 +93,11 @@ paths:
           name: body
           required: true
           description: |-
-            An empty JSON object.
+            Extra data for the tag, e.g. ordering.
           schema:
             type: object
             example: |-
-              {}
+              {"order": 1}
       responses:
         200:
           description:
diff --git a/event-schemas/examples/v1/m.tag b/event-schemas/examples/v1/m.tag
index 28431b73a..1fd3158ed 100644
--- a/event-schemas/examples/v1/m.tag
+++ b/event-schemas/examples/v1/m.tag
@@ -1,8 +1,8 @@
 {
   "type": "m.tag",
   "content": {
-    "tags": [
-      "work"
-    ]
+    "tags": {
+      "work": {}
+    }
   }
 }
diff --git a/event-schemas/schema/v1/m.tag b/event-schemas/schema/v1/m.tag
index 235d442d2..2ec1a55f9 100644
--- a/event-schemas/schema/v1/m.tag
+++ b/event-schemas/schema/v1/m.tag
@@ -11,9 +11,10 @@
       "type": "object",
       "properties": {
         "tags": {
-          "type": "array",
-          "items": {
-            "type": "string"
+          "type": "object",
+          "additionalProperties": {
+            "title": "Tag",
+            "type": "object"
           }
         }
       }
diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst
index 567e50854..c2b65b3e1 100644
--- a/specification/modules/tags.rst
+++ b/specification/modules/tags.rst
@@ -18,6 +18,9 @@ The ``m.tag`` can also be received in a v1 /events response or in the
 events appearing in v1 /events will have a ``room_id`` with the room
 the tags are for.
 
+Each tag has an associated JSON object with information about the tag, e.g how
+to order the tags.
+
 {{m_tag_event}}
 
 Client Behaviour