diff --git a/changelogs/client_server/newsfragments/2064.clarification b/changelogs/client_server/newsfragments/2064.clarification new file mode 100644 index 00000000..17cc2890 --- /dev/null +++ b/changelogs/client_server/newsfragments/2064.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 index 6329495c..3a4a14a5 100644 --- a/data/api/client-server/space_hierarchy.yaml +++ b/data/api/client-server/space_hierarchy.yaml @@ -88,7 +88,18 @@ 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. + + The server should return any rooms where at least one of the following conditions is true: + + * The requesting user is currently a member (their [room membership](#room-membership) is `join`). + * The requesting user already has permission to join, i.e. one of the following: + * The user's room membership is `invite`. + * The room's [join rules](#mroomjoin_rules) are set to `public`. + * The room's join rules are set to [`restricted`](#restricted-rooms), provided the user meets one of the specified conditions. + * The room is "knockable" (the room's join rules are set to `knock`, or `knock_restricted`, in a room version that supports those settings). + * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`. items: allOf: - $ref: definitions/public_rooms_chunk.yaml