Update the room tagging documentation

api/client-server/tags.yaml

@@ -43,14 +43,14 @@ paths:
           required: true
           description: |-
             The id of the user to get tags for. The access token must be
-            authorized to make requests for this user id.
+            authorized to make requests for this user ID.
           x-example: "@alice:example.com"
         - in: path
           type: string
           name: roomId
           required: true
           description: |-
-            The id of the room to get tags for.
+            The ID of the room to get tags for.
           x-example: "!726s6s6q:example.com"
       responses:
         200:
@@ -60,16 +60,26 @@ 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"},
-                  "u.Customers": {}
-                }
+              "tags": {
+                "m.favourite": {"order": 0.1},
+                "u.Work": {"order": 0.7},
+                "u.Customers": {}
               }
+            }
       tags:
         - User data
   "/user/{userId}/rooms/{roomId}/tags/{tag}":
@@ -87,40 +97,48 @@ paths:
           required: true
           description: |-
             The id of the user to add a tag for. The access token must be
-            authorized to make requests for this user id.
+            authorized to make requests for this user ID.
           x-example: "@alice:example.com"
         - in: path
           type: string
           name: roomId
           required: true
           description: |-
-            The id of the room to add a tag to.
+            The ID of the room to add a tag to.
           x-example: "!726s6s6q:example.com"
         - in: path
           type: string
           name: tag
           required: true
           description: |-
             The tag to add.
-          x-example: "work"
+          x-example: "u.work"
         - in: body
           name: body
           required: true
           description: |-
             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:
             The tag was successfully added.
           schema:
             type: object
           examples:
-            application/json: {
-              }
+            application/json: {}
       tags:
         - User data
     delete:
@@ -137,30 +155,29 @@ paths:
           required: true
           description: |-
             The id of the user to remove a tag for. The access token must be
-            authorized to make requests for this user id.
+            authorized to make requests for this user ID.
           x-example: "@alice:example.com"
         - in: path
           type: string
           name: roomId
           required: true
           description: |-
-            The id of the room to remove a tag from.
+            The ID of the room to remove a tag from.
           x-example: "!726s6s6q:example.com"
         - in: path
           type: string
           name: tag
           required: true
           description: |-
             The tag to remove.
-          x-example: "work"
+          x-example: "u.work"
       responses:
         200:
           description:
-            The tag was successfully removed
+            The tag was successfully removed.
           schema:
             type: object
           examples:
-            application/json: {
-              }
+            application/json: {}
       tags:
         - User data

changelogs/client_server/newsfragments/1606.clarification

@@ -0,0 +1 @@
+Clarify the room tag structure (thanks @KitsuneRal!)

event-schemas/examples/m.tag

@@ -2,7 +2,7 @@
   "type": "m.tag",
   "content": {
     "tags": {
-      "u.work": {"order": 1}
+      "u.work": {"order": 0.9}
     }
   }
 }

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."
+              }
+            }
           }
         }
       }

specification/modules/tags.rst

@@ -39,7 +39,7 @@ with an ``order`` of ``0.2`` would be displayed before a room with an ``order``
 of ``0.7``. If a room has a tag without an ``order`` key then it should appear 
 after the rooms with that tag that have an ``order`` key.
 
-The name of a tag MUST not exceed 255 bytes.
+The name of a tag MUST NOT exceed 255 bytes.
 
 The tag namespace is defined as follows: