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
+1. If the room has an `m.room.name`_ state event with a non-empty ``name``
-   event.
+   field, use the name given by that field.
 
-#. If the room has an `m.room.canonical_alias`_ state event, use the alias
+#. If the room has an `m.room.canonical_alias`_ state event with a non-empty
-   given by that event.
+   ``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
+#. If the room has no valid ``m.room.name`` or ``m.room.canonical_alias``
-   no active members other than the current user, clients should consider
+   event, and no active members other than the current user, clients should
-   ``m.room.member`` events with ``membership: leave``. If such events exist, a
+   consider ``m.room.member`` events with ``membership: leave``. If such events
-   display name such as "Empty room (was <user1> and <N> others)" (or a
+   exist, a display name such as "Empty room (was <user1> and <N> others)" (or
-   localised variant thereof) should be used, following similar rules as for
+   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
+#. A complete absence of room name, canonical alias, and room members is likely
-   ``m.room.member`` events is likely to indicate a problem with creating the
+   to indicate a problem with creating the room or synchronising the state
-   room or synchronising the state table; however clients should still handle
+   table; however clients should still handle this situation. A display name
-   this situation. A display name such as "Empty room" (or a localised variant
+   such as "Empty room" (or a localised variant thereof) should be used in this
-   thereof) should be used in this situation.
+   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
 ----------------