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/event-schemas/examples/m.space.child.yaml

@@ -0,0 +1,10 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.space.child",
+  "state_key": "!roomid:example.org",
+  "content": {
+    "suggested": true,
+    "via": ["example.org", "other.example.org"],
+    "order": "lexicographically_compare_me"
+  }
+}

data/event-schemas/examples/m.space.parent.yaml

@@ -0,0 +1,9 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.space.parent",
+  "state_key": "!parent_roomid:example.org",
+  "content": {
+    "canonical": true,
+    "via": ["example.org", "other.example.org"]
+  }
+}

data/event-schemas/schema/m.room.create.yaml

@@ -14,6 +14,12 @@ properties:
       room_version:
         description: The version of the room. Defaults to `"1"` if the key does not exist.
         type: string
+      type:
+        description: |-
+          Optional [room type](#types) to denote a room's intended function outside of traditional conversation.
+
+          Unspecified room types are possible using [Namespaced Identifiers](/appendices/#common-namespaced-identifier-grammar).
+        type: string
       predecessor:
         description: A reference to the room this room replaces, if the previous room was upgraded.
         type: object

data/event-schemas/schema/m.space.child.yaml

@@ -0,0 +1,46 @@
+---
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: Defines the relationship of a child room to a space-room. Has no effect in rooms which are not [spaces](#spaces).
+properties:
+  content:
+    properties:
+      via:
+        type: array
+        description: |-
+          A list of servers to try and join through. See also: [Routing](/appendices/#routing).
+
+          When not present or invalid, the child room is not considered to be part of the space.
+        items:
+          type: string
+      order:
+        type: string
+        maxLength: 50
+        pattern: '^[\x20-\x7E]+$'
+        description: |-
+          Optional string to define ordering among space children. These are lexicographically
+          compared against other children's `order`, if present.
+
+          Must consist of ASCII characters within the range `\x20` (space) and `\x7E` (`~`),
+          inclusive. Must not exceed 50 characters.
+
+          `order` values with the wrong type, or otherwise invalid contents, are to be treated
+          as though the `order` key was not provided.
+
+          See [Ordering](/client-server-api/#ordering-1) for information on how the ordering works.
+      suggested:
+        type: boolean
+        description: |-
+          Optional (default `false`) flag to denote whether the child is "suggested" or of interest
+          to members of the space. This is primarily intended as a rendering hint for clients to
+          display the room differently, such as eagerly rendering them in the room list.
+    type: object
+  state_key:
+    description: The child room ID being described.
+    type: string
+  type:
+    enum:
+      - m.space.child
+    type: string
+title: Space child room
+type: object

data/event-schemas/schema/m.space.parent.yaml

@@ -0,0 +1,32 @@
+---
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: Defines the relationship of a room to a parent space-room.
+properties:
+  content:
+    properties:
+      via:
+        type: array
+        description: |-
+          A list of servers to try and join through. See also: [Routing](/appendices/#routing).
+
+          When not present or invalid, the room is not considered to be part of the parent space.
+        items:
+          type: string
+      canonical:
+        type: boolean
+        description: |-
+          Optional (default `false`) flag to denote this parent is the primary parent for the room.
+
+          When multiple `canonical` parents are found, the lowest parent when ordering by room ID
+          lexicographically by Unicode code-points should be used.
+    type: object
+  state_key:
+    description: The parent room ID.
+    type: string
+  type:
+    enum:
+      - m.space.parent
+    type: string
+title: Room space parent
+type: object