Merge pull request #351 from matrix-org/rav/room_naming

Clarify the room-naming behaviour

event-schemas/schema/m.room.canonical_alias

@@ -1,7 +1,14 @@
 ---
 allOf:
   - $ref: core-event-schema/state_event.yaml
-description: This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.
+description: |-
+    This event is used to inform the room about which alias should be
+    considered the canonical one. This could be for display purposes or as
+    suggestion to users which alias to use to advertise the room.
+
+    A room with an ``m.room.canonical_alias`` event with an absent, null, or
+    empty ``alias`` field should be treated the same as a room with no
+    ``m.room.canonical_alias`` event.
 properties:
   content:
     properties:
@@ -9,6 +16,8 @@ properties:
         description: The canonical alias.
         type: string
     type: object
+    required:
+      - alias
   state_key:
     description: A zero-length string.
     pattern: '^$'

event-schemas/schema/m.room.name

@@ -1,7 +1,18 @@
 ---
 allOf:
   - $ref: core-event-schema/state_event.yaml
-description: 'A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set. The room name can also be set when creating a room using ``/createRoom`` with the ``name`` key.'
+description: |-
+    A room has an opaque room ID which is not human-friendly to read. A room
+    alias is human-friendly, but not all rooms have room aliases. The room name
+    is a human-friendly string designed to be displayed to the end-user. The
+    room name is not unique, as multiple rooms can have the same room name set.
+
+    A room with an ``m.room.name`` event with an absent, null, or empty
+    ``name`` field should be treated the same as a room with no ``m.room.name``
+    event.
+
+    An event of this type is automatically created when creating a room using
+    ``/createRoom`` with the ``name`` key.
 properties:
   content:
     properties:

specification/modules/instant_messaging.rst

@@ -189,13 +189,13 @@ of possibilities for choosing a useful name. To ensure that rooms are named
 consistently across clients, clients SHOULD use the following algorithm to
 choose a name:
 
-1. If the room has an `m.room.name`_ state event, use the name given by that
-   event.
+1. If the room has an `m.room.name`_ state event with a non-empty ``name``
+   field, use the name given by that field.
 
-#. If the room has an `m.room.canonical_alias`_ state event, use the alias
-   given by that event.
+#. If the room has an `m.room.canonical_alias`_ state event with a non-empty
+   ``alias`` field, use the alias given by that field as the name.
 
-#. If neither of the above events are present, a name should be composed based
+#. If neither of the above conditions are met, a name should be composed based
    on the members of the room. Clients should consider `m.room.member`_ events
    for users other than the logged-in user, with ``membership: join`` or
    ``membership: invite``.
@@ -235,18 +235,18 @@ choose a name:
 
      See https://matrix.org/jira/browse/SPEC-267 for further discussion.
 
-#. If the room has no ``m.room.name`` or ``m.room.canonical_alias`` events, and
-   no active members other than the current user, clients should consider
-   ``m.room.member`` events with ``membership: leave``. If such events exist, a
-   display name such as "Empty room (was <user1> and <N> others)" (or a
-   localised variant thereof) should be used, following similar rules as for
+#. If the room has no valid ``m.room.name`` or ``m.room.canonical_alias``
+   event, and no active members other than the current user, clients should
+   consider ``m.room.member`` events with ``membership: leave``. If such events
+   exist, a display name such as "Empty room (was <user1> and <N> others)" (or
+   a localised variant thereof) should be used, following similar rules as for
    active members (see `above <active_members_>`_).
 
-#. A complete absence of ``m.room.name``, ``m.room.canonical_alias``, and
-   ``m.room.member`` events is likely to indicate a problem with creating the
-   room or synchronising the state table; however clients should still handle
-   this situation. A display name such as "Empty room" (or a localised variant
-   thereof) should be used in this situation.
+#. A complete absence of room name, canonical alias, and room members is likely
+   to indicate a problem with creating the room or synchronising the state
+   table; however clients should still handle this situation. A display name
+   such as "Empty room" (or a localised variant thereof) should be used in this
+   situation.
 
 .. _`disambiguated display name`: `Calculating the display name for a user`_
 
@@ -256,8 +256,8 @@ change unexpectedly.
 
 .. TODO-spec
   How can we make this less painful for clients to implement, without forcing
-  an English-language implementation on them all?
-
+  an English-language implementation on them all? See
+  https://matrix.org/jira/browse/SPEC-425.
 
 Server behaviour
 ----------------