Minor touchups to the room tagging API

Fixes some of https://github.com/matrix-org/matrix-doc/issues/1565

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:
@@ -74,12 +74,12 @@ paths:
                   additionalProperties: true
           examples:
             application/json: {
-                "tags": {
+              "tags": {
-                  "m.favourite": {"order": 0.1},
+                "m.favourite": {"order": 0.1},
-                  "u.Work": {"order": 0.7},
+                "u.Work": {"order": 0.7},
-                  "u.Customers": {}
+                "u.Customers": {}
-                }
               }
+            }
       tags:
         - User data
   "/user/{userId}/rooms/{roomId}/tags/{tag}":
@@ -97,14 +97,14 @@ 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
@@ -112,7 +112,7 @@ paths:
           required: true
           description: |-
             The tag to add.
-          x-example: "work"
+          x-example: "u.work"
         - in: body
           name: body
           required: true
@@ -138,8 +138,7 @@ paths:
           schema:
             type: object
           examples:
-            application/json: {
+            application/json: {}
-              }
       tags:
         - User data
     delete:
@@ -156,14 +155,14 @@ 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
@@ -171,15 +170,14 @@ paths:
           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

event-schemas/examples/m.tag

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

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: