From 7c3e5148aca2470a34f1bbba244de8bc344914ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Wed, 22 Apr 2026 12:19:15 +0200
Subject: [PATCH] Clarify string formats in user data endpoints
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 data/api/client-server/profile.yaml | 18 +++++++++++++-----
 data/api/client-server/users.yaml   |  4 +++-
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 4e34503a..5e66f1a9 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -46,6 +46,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: keyName
           description: The name of the profile field to set. This MUST be either
@@ -69,11 +71,11 @@ paths:
               description: |
                 An object which contains exactly one property. The key
                 of that property MUST match the `keyName` specified in the URL.
-                
-                For `avatar_url`, the value MUST be an MXC URI string. 
-                
+
+                For `avatar_url`, the value MUST be an MXC URI string.
+
                 For `displayname`, the value MUST be a string.
-                
+
                 For `m.tz`, the value MUST be a valid identifier from the  [IANA Time Zone Database](https://www.iana.org/time-zones).
                 Servers MAY choose to validate the value. Clients MUST expect unknown or invalid
                 values.
@@ -96,7 +98,7 @@ paths:
           description: |
             The input was invalid in some way. This can include one
             of the following error codes:
-            
+
             - `M_BAD_JSON`: The provided value is not valid JSON.
             - `M_MISSING_PARAM`: The required `keyName` property is
               missing from the request body.
@@ -158,6 +160,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: keyName
           description: The name of the profile field to retrieve.
@@ -216,6 +220,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: keyName
           description: The name of the profile field to delete.
@@ -286,6 +292,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
       responses:
         "200":
           description: The profile information for this user.
diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml
index c1f3c6c8..79906820 100644
--- a/data/api/client-server/users.yaml
+++ b/data/api/client-server/users.yaml
@@ -30,7 +30,7 @@ paths:
             `public` [join rule](#mroomjoin_rules)
         -   users who are joined to rooms known to the homeserver that have a
             `world_readable` [history visibility](#room-history-visibility)
-        
+
         The search MUST consider local users to the homeserver, and SHOULD
         query remote users as part of the search.
 
@@ -82,6 +82,8 @@ paths:
                           type: string
                           example: "@foo:bar.com"
                           description: The user's matrix user ID.
+                          format: mx-user-id
+                          pattern: "^@"
                         display_name:
                           type: string
                           example: Foo