Add Spaces to the spec (#3610)

* First iteration of specifying Spaces

MSCs:
* https://github.com/matrix-org/matrix-doc/pull/3288
* https://github.com/matrix-org/matrix-doc/pull/2946
* https://github.com/matrix-org/matrix-doc/pull/1772

Note that this makes modifications to the underlying MSCs as well. These are intended to be minor edits to aid clarity/accuracy of the MSCs, as per the proposal process. Functionally, clients and servers might need to change their behaviour slightly as is expected of implementing this stuff early. Synapse has these changes (alongside backwards compatibility) here: https://github.com/matrix-org/synapse/pull/11667

* add changelogs

* Accuracy per review

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* fully prefix new endpoints

* Fully prefix endpoint in 3616 too

* Fix ordering example

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

data/api/client-server/definitions/public_rooms_chunk.yaml

@@ -0,0 +1,70 @@
+# Copyright 2021 The Matrix.org Foundation C.I.C.
+#
+# 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.
+
+type: object
+title: "PublicRoomsChunk"
+properties:
+  aliases:
+    type: array
+    description: Aliases of the room. May be empty.
+    items:
+      type: string
+    example: ["#general:example.org"]
+  canonical_alias:
+    type: string
+    description: The canonical alias of the room, if any.
+    example: "#general:example.org"
+  name:
+    type: string
+    description: The name of the room, if any.
+    example: "General Chat"
+  num_joined_members:
+    type: integer
+    description: The number of members joined to the room.
+    example: 42
+  room_id:
+    type: string
+    description: The ID of the room.
+    example: "!abcdefg:example.org"
+  topic:
+    type: string
+    description: The topic of the room, if any.
+    example: "All things general"
+  world_readable:
+    type: boolean
+    description: Whether the room may be viewed by guest users without joining.
+    example: false
+  guest_can_join:
+    type: boolean
+    description: |-
+      Whether guest users may join the room and participate in it.
+      If they can, they will be subject to ordinary power level
+      rules like any other user.
+    example: true
+  avatar_url:
+    type: string
+    format: uri
+    description: The URL for the room's avatar, if one is set.
+    example: "mxc://example.org/abcdef"
+  join_rule:
+    type: string
+    description: |-
+      The room's join rule. When not present, the room is assumed to
+      be `public`.
+    example: "public"
+required:
+  - room_id
+  - num_joined_members
+  - world_readable
+  - guest_can_join

data/api/client-server/definitions/public_rooms_response.yaml

@@ -22,61 +22,19 @@ properties:
     description: |-
       A paginated chunk of public rooms.
     items:
-      type: object
-      title: "PublicRoomsChunk"
-      required:
-        - room_id
-        - num_joined_members
-        - world_readable
-        - guest_can_join
-      properties:
-        aliases:
-          type: array
-          description: |-
-            Aliases of the room. May be empty.
-          items:
-            type: string
-        canonical_alias:
-          type: string
-          description: |-
-            The canonical alias of the room, if any.
-        name:
-          type: string
-          description: |-
-            The name of the room, if any.
-        num_joined_members:
-          type: integer
-          description: |-
-            The number of members joined to the room.
-        room_id:
-          type: string
-          description: |-
-            The ID of the room.
-        topic:
-          type: string
-          description: |-
-            The topic of the room, if any.
-        world_readable:
-          type: boolean
-          description: |-
-            Whether the room may be viewed by guest users without joining.
-        guest_can_join:
-          type: boolean
-          description: |-
-            Whether guest users may join the room and participate in it.
-            If they can, they will be subject to ordinary power level
-            rules like any other user.
-        avatar_url:
-          type: string
-          format: uri
-          description: The URL for the room's avatar, if one is set.
-        join_rule:
-          type: string
-          description: |-
-            The room's join rule. When not present, the room is assumed to
-            be `public`. Note that rooms with `invite` join rules are not
-            expected here, but rooms with `knock` rules are given their
-            near-public nature.
+      allOf:
+        - $ref: "public_rooms_chunk.yaml"
+        - type: object
+          properties:
+            # Override description of join_rule
+            join_rule:
+              type: string
+              description: |-
+                The room's join rule. When not present, the room is assumed to
+                be `public`. Note that rooms with `invite` join rules are not
+                expected here, but rooms with `knock` rules are given their
+                near-public nature.
+              example: "public"
   next_batch:
     type: string
     description: |-