From 57590f62a3eff9539c68d70a6ae0bba6e40e73a2 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Fri, 5 Jun 2026 14:04:06 -0600
Subject: [PATCH] Update ordering behaviour for room directory listing

As per MSC4423
---
 data/api/client-server/list_public_rooms.yaml | 16 ++++++++++++----
 data/api/server-server/public_rooms.yaml      | 16 ++++++++++++----
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml
index c3f0280f..b57ecc8d 100644
--- a/data/api/client-server/list_public_rooms.yaml
+++ b/data/api/client-server/list_public_rooms.yaml
@@ -137,8 +137,12 @@ paths:
       description: |-
         Lists a server's published room directory.
 
-        This API returns paginated responses. The rooms are ordered by the number
-        of joined members, with the largest rooms first.
+        This API returns paginated responses.
+
+        {{% changed-in v="1.19" %}} The server determines the order of the rooms
+        returned by this endpoint. Previously, rooms were ordered with the largest
+        joined member count first. Continuing to order by largest first or another
+        stable order is recommended.
       operationId: getPublicRooms
       parameters:
         - in: query
@@ -177,8 +181,12 @@ paths:
       description: |-
         Lists a server's published room directory with an optional filter.
 
-        This API returns paginated responses. The rooms are ordered by the number
-        of joined members, with the largest rooms first.
+        This API returns paginated responses.
+
+        {{% changed-in v="1.19" %}} The server determines the order of the rooms
+        returned by this endpoint. Previously, rooms were ordered with the largest
+        joined member count first. Continuing to order by largest first or another
+        stable order is recommended.
       operationId: queryPublicRooms
       security:
         - accessTokenQuery: []
diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml
index 41835f5a..eb07c918 100644
--- a/data/api/server-server/public_rooms.yaml
+++ b/data/api/server-server/public_rooms.yaml
@@ -22,8 +22,12 @@ paths:
       description: |-
         Lists the server's published room directory.
 
-        This API returns paginated responses. The rooms are ordered by the number
-        of joined members, with the largest rooms first.
+        This API returns paginated responses.
+
+        {{% changed-in v="1.19" %}} The server determines the order of the rooms
+        returned by this endpoint. Previously, rooms were ordered with the largest
+        joined member count first. Continuing to order by largest first or another
+        stable order is recommended.
 
         This SHOULD not return rooms that are listed on another homeserver's directory,
         just those listed on the receiving homeserver's directory.
@@ -76,8 +80,12 @@ paths:
       description: |-
         Lists the server's published room directory with an optional filter.
 
-        This API returns paginated responses. The rooms are ordered by the number
-        of joined members, with the largest rooms first.
+        This API returns paginated responses.
+
+        {{% changed-in v="1.19" %}} The server determines the order of the rooms
+        returned by this endpoint. Previously, rooms were ordered with the largest
+        joined member count first. Continuing to order by largest first or another
+        stable order is recommended.
       operationId: queryPublicRooms
       security:
         - signedRequest: []