From e4fd088fcc7a9357c4551c544a0e84b4d0f3731e Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 27 Jul 2018 12:05:30 +0100 Subject: [PATCH 1/4] Fix room tags spec --- api/client-server/tags.yaml | 6 +++-- specification/modules/tags.rst | 46 ++++++++++++++++------------------ 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml index 9310b25f..42db5d9d 100644 --- a/api/client-server/tags.yaml +++ b/api/client-server/tags.yaml @@ -1,4 +1,5 @@ # Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -64,8 +65,9 @@ paths: examples: application/json: { "tags": { - "work": {"order": "1"}, - "pinned": {} + "m.favourite": {} + "u.Work": {"order": "1"}, + "u.Customers": {} } } tags: diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index 25e48ab3..c085391e 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2018 New Vector Ltd .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -17,22 +18,19 @@ Room Tagging .. _module:tagging: -Users can add tags to rooms. Tags are short strings used to label rooms, e.g. -"work", "family". A room may have multiple tags. Tags are only visible to the -user that set them but are shared across all their devices. +Users can add tags to rooms. Tags are namespaced strings used to label rooms. +A room may have multiple tags. Tags are only visible to the user that set them +but are shared across all their devices. Events ------ The tags on a room are received as single ``m.tag`` event in the -``account_data`` section of a room in a ``/sync``. +``account_data`` section of a room. The content of the ``m.tag`` event is a +``tags`` key whose value is an object mapping the name of each tag to another +object. -The ``m.tag`` can also be received in a ``/events`` response or in the -``account_data`` section of a room in ``/initialSync``. ``m.tag`` -events appearing in ``/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 +The JSON object associated with each tag gives information about the tag, e.g how to order the rooms with a given tag. Ordering information is given under the ``order`` key as a number between 0 and @@ -43,26 +41,26 @@ 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 should be human readable. When displaying tags for a room a -client should display this human readable name. When adding a tag for a room -a client may offer a list to choose from that includes all the tags that the -user has previously set on any of their rooms. +Tags namespaces are defined in the following way, depending on how the client are expected to interpret them: + +* The namespace ``m.*`` is reserved for tags defined in the Matrix specification +* The namespace ``u.*`` is reserved for user-defined tags. The portion of the string after the ``u.`` + is defined to be the display name of this tag. No other semantics should be inferred from tags in + this namespace. +* A client or app willing to use special tags for advanced functionnality should namespace them similarly to state keys: ``tld.name.*`` +* Any tag in the ``tld.name.*`` form but not matching the namespace of the current client should be ignored +* Any tag not matching the above rules should be interpreted as a user tag from the ``u.*`` namespace, as if + the name had already had ``u.`` stripped from the start (ie. the name of the tag is used as the + display name directly). Two special names are listed in the specification: +The following tags are defined in the ``m.*`` namespace: -* ``m.favourite`` -* ``m.lowpriority`` +* ``m.favourite``: The user's favourite rooms. These should be shown with higher precedence than other rooms. +* ``m.lowpriority``: These should be shown with lower precedence than others. {{m_tag_event}} -Tags namespaces are defined in the following way, depending on how the client are expected to interpret them: - -* The namespace ``m.*`` is reserved for tags defined in the current specification -* The namespace ``u.*`` is reserved for user-defined tags, and the client should not try to interpret as anything other than an utf8 string -* A client or app willing to use special tags for advanced functionnality should namespace them similarly to state keys: ``tld.name.*`` -* Any tag in the ``tld.name.*`` form but not matching the namespace of the current client should be ignored -* Any tag not matching the previous rules should be interpreted as an user tag from the ``u.*`` namespace - Client Behaviour ---------------- From f90ed4b77d19363667e11f8dd4555a49e3fe3700 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 27 Jul 2018 12:08:04 +0100 Subject: [PATCH 2/4] Make non-namespaced tags verboten --- specification/modules/tags.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index c085391e..bf985ede 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -51,7 +51,8 @@ Tags namespaces are defined in the following way, depending on how the client ar * Any tag in the ``tld.name.*`` form but not matching the namespace of the current client should be ignored * Any tag not matching the above rules should be interpreted as a user tag from the ``u.*`` namespace, as if the name had already had ``u.`` stripped from the start (ie. the name of the tag is used as the - display name directly). + display name directly). These non-namespaced tags are supported for historical reasons. New tags should use + one of the defined namespaces above. Two special names are listed in the specification: The following tags are defined in the ``m.*`` namespace: From 5ddf5374db3dc80fcb093946ff5c6c5465b5e75f Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 27 Jul 2018 12:24:29 +0100 Subject: [PATCH 3/4] Missing comma --- api/client-server/tags.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml index 42db5d9d..b7bafab6 100644 --- a/api/client-server/tags.yaml +++ b/api/client-server/tags.yaml @@ -65,7 +65,7 @@ paths: examples: application/json: { "tags": { - "m.favourite": {} + "m.favourite": {}, "u.Work": {"order": "1"}, "u.Customers": {} } From 2dc51d416dddad4932a78c9b0e1128fe68b985de Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 27 Jul 2018 12:27:30 +0100 Subject: [PATCH 4/4] Ignore stuff in `m.` you don't understand --- specification/modules/tags.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index bf985ede..8c74c55f 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -43,7 +43,8 @@ The name of a tag MUST not exceed 255 bytes. Tags namespaces are defined in the following way, depending on how the client are expected to interpret them: -* The namespace ``m.*`` is reserved for tags defined in the Matrix specification +* The namespace ``m.*`` is reserved for tags defined in the Matrix specification. Clients must ignore + any tags in this namespace they don't understand. * The namespace ``u.*`` is reserved for user-defined tags. The portion of the string after the ``u.`` is defined to be the display name of this tag. No other semantics should be inferred from tags in this namespace.