From 9bc14703058adc3558d83f16fadcdf5f92cf8c3a Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 26 Aug 2018 20:25:05 +0900 Subject: [PATCH 1/3] Elaborate the structure of m.tag events ...and corresponding structures in tag-related CS API calls Signed-off-by: Alexey Rusakov --- 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 b7bafab60..108095720 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 80d3f9dd3..8da093bd5 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." + } + } } } } From c03f2f8d79ac9f589249890382a204ad1158972b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 14:53:55 -0600 Subject: [PATCH 2/3] Minor touchups to the room tagging API Fixes some of https://github.com/matrix-org/matrix-doc/issues/1565 --- api/client-server/tags.yaml | 34 ++++++++++++++++------------------ event-schemas/examples/m.tag | 2 +- specification/modules/tags.rst | 2 +- 3 files changed, 18 insertions(+), 20 deletions(-) diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml index 108095720..081d8a848 100644 --- a/api/client-server/tags.yaml +++ b/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": { - "m.favourite": {"order": 0.1}, - "u.Work": {"order": 0.7}, - "u.Customers": {} - } + "tags": { + "m.favourite": {"order": 0.1}, + "u.Work": {"order": 0.7}, + "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 diff --git a/event-schemas/examples/m.tag b/event-schemas/examples/m.tag index 53dbc921a..e5564a4b4 100644 --- a/event-schemas/examples/m.tag +++ b/event-schemas/examples/m.tag @@ -2,7 +2,7 @@ "type": "m.tag", "content": { "tags": { - "u.work": {"order": 1} + "u.work": {"order": 0.9} } } } diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index f965c2e82..739ead2c7 100644 --- a/specification/modules/tags.rst +++ b/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: From 30ff020ac75d480d3025748fc803546bb784c415 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 14:57:05 -0600 Subject: [PATCH 3/3] Changelog --- changelogs/client_server/newsfragments/1606.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1606.clarification diff --git a/changelogs/client_server/newsfragments/1606.clarification b/changelogs/client_server/newsfragments/1606.clarification new file mode 100644 index 000000000..f65ed257e --- /dev/null +++ b/changelogs/client_server/newsfragments/1606.clarification @@ -0,0 +1 @@ +Clarify the room tag structure (thanks @KitsuneRal!)