archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clarify introduction and add content queries

Browse Source 
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
pull/4301/head
Johannes Marbach 3 weeks ago
parent 2654cf34d2
commit a4cba60950
1 changed files with 85 additions and 21 deletions
Show Stats Download Patch File Download Diff File

106
proposals/4301-event-capability-negotiation.md
Unescape Escape View File

@ -1,19 +1,27 @@
# MSC4301: Event capability negotiation between clients
Matrix allows clients to exchange both built-in and custom events with other clients in rooms. There
is, however, no way for a client to understand what types of events the other clients in a room are
able to understand. This is problematic as a compatibility mismatch means that the recipient user
might only be able to see a fallback representation of an event or, in the worst case, nothing at
all. At the same time, the sender is left wholly unaware of the recipient's experience.
is, however, no way for a client to tell what types of events the other clients in a room are able
to understand. This is problematic as a compatibility mismatch means that the recipient user might
only be able to see a fallback representation of an event or, in the worst case, nothing at all. At
the same time, the sender is left wholly unaware of the recipient's experience.
A glaring example of this occurs when Matrix is used to exchange [FHIR] resources, e.g. via
[MSC4302]. These resources can be subject to complex customizations via so called *profiles* which
affect rendering and processing logic. For a client that aims to send FHIR resources into a room, it
is, therefore, crucial to know whether or not the recipients in the room can actually work with the
specific FHIR profiles it is going to use. The usual Matrix approach of designing new events to
include backwards-compatible fallbacks is not feasible in this case. The only apparent fallback is
transmitting FHIR resources as generic JSON or XML files. Such files are not (easily) human-readable
and will appear mostly impractical to recipients, however.
[MSC4300] partially addresses this problem by enabling clients to communicate the result of
processing a specific event back to the sender. This lets senders determine after the fact whether
the events they have sent were understood by other clients or not.
The present proposal goes a step further and introduces a scheme for clients to query whether other
clients understand an event type *ahead* of actually sending that event. This allows clients to
efficiently negotiate compatible event types resulting in the best possible experience for all
participants.
This proposal goes a step further and introduces a scheme for clients to query whether other clients
understand an event *ahead* of actually sending it. This allows clients to efficiently negotiate
compatible event types resulting in the best possible experience for all participants.
## Proposal
@ -25,7 +33,13 @@ properties in `content`:
- `m.request.status` (object, required): Generic information about the request as per [MSC4300].
- `m.request.event_capability` (object, required): Information about the event capability request.
- `types` (array, required): A list of event types for which the sender wishes to request support.
- `events` (array, required): A list of objects containing details about the events being queried.
- `type` (string, required): The type of the event.
- `content` (array): An optional list of objects describing additional requirements for
properties inside the `content` of the event.
- `key` (string, required): The dot-separated path of the property (analogous to `key` in
`event_match` [push rule conditions]).
- `value` (string, required): The exact value of the property.
``` json5
{
@ -37,24 +51,57 @@ properties in `content`:
"from_device": "RJYKSTBOIE",
"lifetime": 90_000, // 90s
},
// I'd like to send any of these event types into this room.
// I'd like to send any of these events into this room.
// Which of these do you understand?
"m.request.event_capability": {
"types": [
"m.pizza.margherita",
"m.pizza.salami",
"m.pizza.hawaii"
"events": [
// How about m.fhir containing advanced rendering SDC questionnaires v4?
{
"type": "m.fhir",
"content": [{
"key": "m\.fhir\.structure_definition.url",
"value": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-render"
}, {
"key": "m\.fhir\.structure_definition.version",
"value": "4.0.0"
}]
},
// Or if you don't know v4, maybe you support v3?
{
"type": "m.fhir",
"content": [{
"key": "m\.fhir\.structure_definition.url",
"value": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-render"
}, {
"key": "m\.fhir\.structure_definition.version",
"value": "3.0.0"
}]
},
// Or failing that, do you at least understand base SDC questionnaires v4?
{
"type": "m.fhir",
"content": [{
"key": "m\.fhir\.structure_definition.url",
"value": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire"
}, {
"key": "m\.fhir\.structure_definition.version",
"value": "4.0.0"
}]
}
]
}
}
}
```
The requirements expressed through `type` and the elements of `content` are to be combined using
logical AND.
Recipient clients MAY respond to `m.request.event_capability` within its lifetime with the
`m.response.status` event from [MSC4300] and the following additional properties in `content`:
- `m.response.event_capability` (object, required): Information about the event capability response
- `types` (array, required): The subset of event types from `m.request.event_capability` that the
- `events` (array, required): The subset of events from `m.request.event_capability` that the
sending device is able to understand.
``` json5
@ -67,18 +114,27 @@ Recipient clients MAY respond to `m.request.event_capability` within its lifetim
"status": "success",
"messages": [{
"type": "info",
"m.text": [{ "body": "Refusing to recognise Hawaii as a Pizza style!" }]
"m.text": [{ "body": "Unknown structure definition http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-render" }]
}]
},
"m.relates_to": {
"event_id": "$1",
"rel_type": "m.reference",
},
// These are the event types I understand.
// These are the events I understand.
"m.response.event_capability": {
"types": [
"m.pizza.margherita",
"m.pizza.salami",
"events": [
// I can only do m.fhir with base SDC questionnaires, sorry!
{
"type": "m.fhir",
"content": [{
"key": "m\.fhir\.structure_definition.url",
"value": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire"
}, {
"key": "m\.fhir\.structure_definition.version",
"value": "4.0.0"
}]
}
]
}
}
@ -96,6 +152,11 @@ events that they are able to understand, for instance, via profiles or state eve
would simplify looking up capabilities but comes with its own technical challenges such as scoping
profiles to devices and rooms or being able to send state events in a room.
Rather than allowing specific requirements on `content` fields, queries could be limited to only
event types. This would noticeably simplify the scheme. However, particularly in the case of FHIR,
it seems impractical to define event types for every possible resource or profile in their various
versions.
## Security considerations
The concerns and remedies around leaking metadata from [MSC4300] apply to this proposal as well.
@ -110,6 +171,9 @@ and `de.gematik.msc4301.response.event_capability`, respectively. Properties inh
## Dependencies
This proposal builds on [MSC4300] which at the time of writing has not yet been accepted into the
spec.
spec. This proposal does not depend on [MSC4302] but is intended to work in concert with it.
[FHIR]: https://www.hl7.org/fhir/
[MSC4302]: https://github.com/matrix-org/matrix-spec-proposals/pull/4302
[MSC4300]: https://github.com/matrix-org/matrix-spec-proposals/pull/4300
[push rule conditions]: https://spec.matrix.org/v1.16/client-server-api/#conditions-1

Write Preview
Loading…
Cancel
Save