diff --git a/changelogs/client_server/newsfragments/2376.clarification b/changelogs/client_server/newsfragments/2376.clarification new file mode 100644 index 00000000..bdcce777 --- /dev/null +++ b/changelogs/client_server/newsfragments/2376.clarification @@ -0,0 +1 @@ +Clarify formats of string types. diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index ac0a232c..f373d14b 100644 --- a/content/client-server-api/modules/receipts.md +++ b/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. diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index c68ef3f6..40f581d3 100644 --- a/data/api/client-server/receipts.yaml +++ b/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). diff --git a/data/event-schemas/schema/m.receipt.yaml b/data/event-schemas/schema/m.receipt.yaml index 1f3b0912..c817e467 100644 --- a/data/event-schemas/schema/m.receipt.yaml +++ b/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: |-