Improve "Receipts" module of CS API (#2376)

* Add links to definitions and clarify string formats of Receipts section

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/2376.clarification

@@ -0,0 +1 @@
+Clarify formats of string types.

content/client-server-api/modules/receipts.md

@@ -90,11 +90,11 @@ room that the event was sent to or dismissing a notification in order
 for the event to count as "read". Clients SHOULD NOT send read receipts
 for events sent by their own user.
 
-Similar to the rules for sending receipts, threaded receipts should appear
-in the context of the thread. If a thread is rendered behind a disclosure,
-the client hasn't yet shown the event (or any applicable read receipts)
-to the user. Once they expand the thread though, a threaded read receipt
-would be sent and per-thread receipts from other users shown.
+Similar to the rules for sending receipts, [threaded receipts](#threaded-read-receipts)
+should appear in the context of the thread. If a thread is rendered behind a
+disclosure, the client hasn't yet shown the event (or any applicable read
+receipts) to the user. Once they expand the thread though, a threaded read
+receipt would be sent and per-thread receipts from other users shown.
 
 A client can update the markers for its user by interacting with the
 following HTTP APIs.
@@ -232,5 +232,5 @@ MUST NOT appear in this federated `m.receipt` EDU.
 
 #### Security considerations
 
-As receipts are sent outside the context of the event graph, there are
-no integrity checks performed on the contents of `m.receipt` events.
+As receipts are sent outside the context of the [event graph](/#event-graphs),
+there are no integrity checks performed on the contents of `m.receipt` events.

data/api/client-server/receipts.yaml

@@ -35,6 +35,8 @@ paths:
           example: "!wefuh21ffskfuh345:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: receiptType
           description: |-
@@ -62,6 +64,8 @@ paths:
           example: $1924376522eioj:example.com
           schema:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
       requestBody:
         content:
           application/json:
@@ -72,7 +76,8 @@ paths:
                   type: string
                   x-addedInMatrixVersion: "1.4"
                   description: |-
-                    The root thread event's ID (or `main`) for which
+                    The [thread root](/client-server-api/#threading)'s
+                    [event ID](/appendices#event-ids) (or `main`) for which
                     thread this receipt is intended to be under. If
                     not specified, the read receipt is *unthreaded*
                     (default).

data/event-schemas/schema/m.receipt.yaml

@@ -27,7 +27,7 @@ properties:
                         type: object
                         description: |-
                             A collection of users who have sent `m.read` receipts for
-                            this event. The string key is the user ID the receipt 
+                            this event. The string key is the user ID the receipt
                             belongs to.
                         patternProperties:
                             "^@": &receiptUserMap
@@ -46,10 +46,10 @@ properties:
                                         type: string
                                         x-addedInMatrixVersion: "1.4"
                                         description: |-
-                                            The root thread event's ID (or `main`) for which
-                                            thread this receipt is intended to be under. If
-                                            not specified, the read receipt is *unthreaded*
-                                            (default).
+                                            The [thread root](/client-server-api/#threading)'s
+                                            [event ID](/appendices#event-ids) (or `main`) for which
+                                            thread this receipt is intended to be under. If not
+                                            specified, the read receipt is *unthreaded* (default).
                     "m.read.private":
                         type: object
                         description: |-