From 9bc14703058adc3558d83f16fadcdf5f92cf8c3a Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Sun, 26 Aug 2018 20:25:05 +0900
Subject: [PATCH] Elaborate the structure of m.tag events

...and corresponding structures in tag-related CS API calls

Signed-off-by: Alexey Rusakov <Alexey.Rusakov@pm.me>
---
 api/client-server/tags.yaml | 27 +++++++++++++++++++++++----
 event-schemas/schema/m.tag  | 10 +++++++++-
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml
index b7bafab6..10809572 100644
--- a/api/client-server/tags.yaml
+++ b/api/client-server/tags.yaml
@@ -60,13 +60,23 @@ paths:
             type: object
             properties:
               tags:
-                title: Tags
                 type: object
+                additionalProperties:
+                  title: Tag
+                  type: object
+                  properties:
+                    order:
+                      type: number
+                      format: float
+                      description: |-
+                        A number in a range ``[0,1]`` describing a relative
+                        position of the room under the given tag.
+                  additionalProperties: true
           examples:
             application/json: {
                 "tags": {
-                  "m.favourite": {},
-                  "u.Work": {"order": "1"},
+                  "m.favourite": {"order": 0.1},
+                  "u.Work": {"order": 0.7},
                   "u.Customers": {}
                 }
               }
@@ -110,8 +120,17 @@ paths:
             Extra data for the tag, e.g. ordering.
           schema:
             type: object
+            properties:
+              order:
+                type: number
+                format: float
+                description: |-
+                  A number in a range ``[0,1]`` describing a relative
+                  position of the room under the given tag.
+            additionalProperties: true
             example: {
-              "order": "1"}
+              "order": 0.25
+            }
       responses:
         200:
           description:
diff --git a/event-schemas/schema/m.tag b/event-schemas/schema/m.tag
index 80d3f9dd..8da093bd 100644
--- a/event-schemas/schema/m.tag
+++ b/event-schemas/schema/m.tag
@@ -18,7 +18,15 @@
           "description": "The tags on the room and their contents.",
           "additionalProperties": {
             "title": "Tag",
-            "type": "object"
+            "type": "object",
+            "properties": {
+              "order": {
+                "type": "number",
+                "format": "float",
+                "description":
+                  "A number in a range ``[0,1]`` describing a relative position of the room under the given tag."
+              }
+            }
           }
         }
       }