diff --git a/changelog.d/18548.doc b/changelog.d/18548.doc
new file mode 100644
index 000000000..69b073221
--- /dev/null
+++ b/changelog.d/18548.doc
@@ -0,0 +1 @@
+Document that some config options for the user directory are in violation of the Matrix spec.
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 0a3adf021..6918559de 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3808,7 +3808,11 @@ encryption_enabled_by_default_for_room_type: invite
 
 This setting has the following sub-options:
 
-* `enabled` (boolean): Defines whether users can search the user directory. If false then empty responses are returned to all queries. Defaults to `true`.
+* `enabled` (boolean): Defines whether users can search the user directory. If `false` then empty responses are returned to all queries.
+
+  *Warning: While the homeserver may determine which subset of users are searched, the Matrix specification requires homeservers to include (at minimum) users visible in public rooms and users sharing a room with the requester. Using `false` improves performance but violates this requirement.*
+
+  Defaults to `true`.
 
 * `search_all_users` (boolean): Defines whether to search all users visible to your homeserver at the time the search is performed. If set to true, will return all users known to the homeserver matching the search query. If false, search results will only contain users visible in public rooms and users sharing a room with the requester.
 
diff --git a/schema/synapse-config.schema.yaml b/schema/synapse-config.schema.yaml
index a2ba557fe..d9a5a9849 100644
--- a/schema/synapse-config.schema.yaml
+++ b/schema/synapse-config.schema.yaml
@@ -4719,8 +4719,15 @@ properties:
       enabled:
         type: boolean
         description: >-
-          Defines whether users can search the user directory. If false then
+          Defines whether users can search the user directory. If `false` then
           empty responses are returned to all queries.
+
+
+          *Warning: While the homeserver may determine which subset of users are
+          searched, the Matrix specification requires homeservers to include (at
+          minimum) users visible in public rooms and users sharing a room with
+          the requester. Using `false` improves performance but violates this
+          requirement.*
         default: true
       search_all_users:
         type: boolean