Clarify which rooms are returned from /hierarchy

Signed-off-by: Patrick Cloke <clokep@patrick.cloke.us>
matrix-org · Jan 24, 2025 · a8045e1 · a8045e1
1 parent ad17652
commit a8045e1
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 1 deletion.
diff --git a/changelogs/client_server/newsfragments/2063.clarification b/changelogs/client_server/newsfragments/2063.clarification
@@ -0,0 +1 @@
+Clarify which rooms are returned from `/hierarchy`.
diff --git a/data/api/client-server/space_hierarchy.yaml b/data/api/client-server/space_hierarchy.yaml
@@ -88,7 +88,16 @@ paths:
                 properties:
                   rooms:
                     type: array
-                    description: The rooms for the current page, with the current filters.
+                    description: |-
+                       The rooms for the current page, with the current filters.
+
+                       Rooms which the requesting user can request the [stripped state](#) of are returned, this includes:
+
+                       * Any rooms where the requesting user's [room membership](#room-membership) is `join` or `invite`
+                       * Any rooms the user can join:
+                         * Rooms with [join rules](#mroomjoin_rules) set to `join`, `knock`, or `knock_restricted`
+                         * Rooms with a join rule of [`restricted`](#restricted-rooms) if the user meets one of the specified conditions
+                       * Any rooms with [`m.room.history_visibility`](#room-history-visibility) set to `world_readable`.
                     items:
                       allOf:
                         - $ref: definitions/public_rooms_chunk.yaml
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Clarify which rooms are returned from `/hierarchy`.