.. 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.
.. You may obtain a copy of the License at
..
..     http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

Room Tagging
============

.. _module:tagging:

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. 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 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
1. The numbers are compared such that 0 is displayed first. Therefore a room
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 tag namespace is defined as follows:

* 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.
* A client or app willing to use special tags for advanced functionality 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). These non-namespaced tags are supported for historical reasons. New tags should use
  one of the defined namespaces above.

Several special names are listed in the specification:
The following tags are defined in the ``m.*`` namespace:

* ``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.server_notice``: Used to identify `Server Notice Rooms <#module-server-notices>`_.

{{m_tag_event}}

Client Behaviour
----------------

{{tags_cs_http_api}}
