From 2c81e3f7ee83cc70e7ef5caf565e1dde55d17535 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 20 Jun 2025 09:43:44 +0200 Subject: [PATCH 1/5] MSC4302: Exchanging FHIR resources via Matrix events Signed-off-by: Johannes Marbach --- .../4302-\360\237\224\245-resources.md" | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 "proposals/4302-\360\237\224\245-resources.md" diff --git "a/proposals/4302-\360\237\224\245-resources.md" "b/proposals/4302-\360\237\224\245-resources.md" new file mode 100644 index 00000000000..2779a09aa7c --- /dev/null +++ "b/proposals/4302-\360\237\224\245-resources.md" @@ -0,0 +1,83 @@ +# MSC4302: Exchanging FHIR resources via Matrix events + +[FHIR] (pronounced 🔥) is a globally established standard for exchanging healthcare information +electronically. The base building block of FHIR are so called resources, such as [`Patient`]. These +resources can be serialised into JSON or XML which allows them to be transmitted via the [`m.file`] +message type. This is insufficient, however, because a generic MIME type of `application/xml` or +`application/json` doesn't let clients recognise the content as FHIR before downloading it. The +`m.file` mechanism also doesn't allow clients to infer any details about the types of resources +contained in the file ahead of downloading it. Furthermore, in many cases FHIR resources are small +enough to be inlined into Matrix events which significantly simplifies client-side processing. + +This proposal introduces an event type for transmitting FHIR resources and type information over +Matrix in either inlined or uploaded form. + +## Proposal + +A new event type `m.fhir.resource` is introduced with the following properties in `content`: + +- `canonical_url` (string, required): The resource's [canonical URL], that is the globally unique + identifier defining its schema. MAY contain a version suffix separated by `|` as per the FHIR + specification. +- `m.fhir.resource` (object): The serialised JSON if it fits within the [64 KiB event size limit]. + Required if `m.file` is missing. +- `m.file` (object): An [MSC3551] content block describing an uploaded JSON or XML serialisation of + the resource if it is too large to be inlined. Required if `m.fhir.resource` is missing. + +``` json5 +{ + "type": "m.fhir.resource", + "content": { + "canonical_url": "http://hl7.org/fhir/patient.html|4.0.1", + "m.fhir.resource": { + "resourceType" : "Patient", + "name" : [{ + "use" : "official", + "given" : ["John", "James"], + "family" : "Doe" + }], + "gender" : "male", + "birthDate" : "1970-01-01", + // further properties as per the Patient schema + }, + "m.file": { + "url": "mxc://example.org/abcd1234", + "mimetype": "application/json", + // further properties as per MSC3551 + } +} +``` + +## Potential issues + +FHIR includes generic resources such as [`Bundle`] which wrap other resources. The `canonical_url` +will not help clients understand the wrapped content without downloading it in these cases. +Dedicated event types may be introduced in future to cater to these situations. + +## Alternatives + +A dedicated MIME type such as `application/fhir+xml` would allow clients to recognise an uploaded +file as FHIR ahead of the download. It would not provide clients with information about the types of +contained resources, however. Since FHIR supports a vast number of resources it doesn't appear +practical to introduce dedicated mimetypes per resource, version and serialisation format + +## Security considerations + +None. + +## Unstable prefix + +While this MSC is not considered stable, the event type `m.fhir.resource` should be referred to as +`de.gematik.msc4302.fhir.resource`. + +## Dependencies + +None. + + [FHIR]: https://hl7.org/fhir/ + [`Patient`]: http://hl7.org/fhir/R4/patient.html + [`m.file`]: https://spec.matrix.org/v1.14/client-server-api/#mfile + [canonical URL]: https://build.fhir.org/references.html#canonical + [64 KiB event size limit]: https://spec.matrix.org/v1.14/client-server-api/#size-limits + [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 + [`Bundle`]: http://hl7.org/fhir/StructureDefinition/Bundle From 766514246475010cb7cdff027d0b15352e287357 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 20 Jun 2025 19:54:11 +0200 Subject: [PATCH 2/5] Remove the fun --- .../4302-fhir-resources.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename "proposals/4302-\360\237\224\245-resources.md" => proposals/4302-fhir-resources.md (100%) diff --git "a/proposals/4302-\360\237\224\245-resources.md" b/proposals/4302-fhir-resources.md similarity index 100% rename from "proposals/4302-\360\237\224\245-resources.md" rename to proposals/4302-fhir-resources.md From 404ce36a7bba794506e03b936dd7d473c07e02ee Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 23 Jun 2025 09:07:25 +0200 Subject: [PATCH 3/5] Rearrange points from introduction and alternatives section to better convey the motivation --- proposals/4302-fhir-resources.md | 45 ++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/proposals/4302-fhir-resources.md b/proposals/4302-fhir-resources.md index 2779a09aa7c..ae86be1c865 100644 --- a/proposals/4302-fhir-resources.md +++ b/proposals/4302-fhir-resources.md @@ -1,16 +1,19 @@ # MSC4302: Exchanging FHIR resources via Matrix events [FHIR] (pronounced 🔥) is a globally established standard for exchanging healthcare information -electronically. The base building block of FHIR are so called resources, such as [`Patient`]. These +electronically. The base building blocks of FHIR are so called resources, such as [`Patient`]. These resources can be serialised into JSON or XML which allows them to be transmitted via the [`m.file`] -message type. This is insufficient, however, because a generic MIME type of `application/xml` or -`application/json` doesn't let clients recognise the content as FHIR before downloading it. The -`m.file` mechanism also doesn't allow clients to infer any details about the types of resources -contained in the file ahead of downloading it. Furthermore, in many cases FHIR resources are small -enough to be inlined into Matrix events which significantly simplifies client-side processing. - -This proposal introduces an event type for transmitting FHIR resources and type information over -Matrix in either inlined or uploaded form. +message type with a MIME type of `application/fhir+json` or `application/fhir+xml`. The generic MIME +type doesn't provide clients with any information about what resources are contained in the file, +however, and requires them to download it for further processing. This is suboptimal because clients +may want to render only some resources, such as [Questionnaire], with a rich UI. Furthermore, even +if a client chooses to present all FHIR resources as opaque files, users would benefit from getting +some information about a file's content without having to download it. Finally, FHIR resources may +in certain cases be small enough to be inlined into Matrix events which would significantly simplify +client-side processing. + +To address these shortcomings, this proposal introduces an event type for transmitting FHIR +resources and type information over Matrix in either inlined or uploaded form. ## Proposal @@ -28,7 +31,7 @@ A new event type `m.fhir.resource` is introduced with the following properties i { "type": "m.fhir.resource", "content": { - "canonical_url": "http://hl7.org/fhir/patient.html|4.0.1", + "canonical_url": "http://hl7.org/fhir/patient.html|4.0.1", "m.fhir.resource": { "resourceType" : "Patient", "name" : [{ @@ -56,10 +59,16 @@ Dedicated event types may be introduced in future to cater to these situations. ## Alternatives -A dedicated MIME type such as `application/fhir+xml` would allow clients to recognise an uploaded -file as FHIR ahead of the download. It would not provide clients with information about the types of -contained resources, however. Since FHIR supports a vast number of resources it doesn't appear -practical to introduce dedicated mimetypes per resource, version and serialisation format +Dedicated MIME types per resource, version and serialisation format could be introduced. Since FHIR +supports a vast number of resources this doesn't appear practical, however. + +[RFC 2045] allows MIME types to include modifying parameters. The canonical URL could, therefore, be +included alongside the media type[^1]. + + Content-type: application/fhir+json; canonical_url="http://hl7.org/fhir/patient.html|4.0.1" + +This would allow reusing the `m.file` message type but leaks the resource type to the home server in +[`POST /_matrix/media/v3/upload`]. ## Security considerations @@ -74,10 +83,18 @@ While this MSC is not considered stable, the event type `m.fhir.resource` should None. +[^1]: This could also be done by reusing the `profile` parameter from [RFC 6906]. Since the term + "profile" already has a specific meaning within the FHIR standard, this could be confusing, + however. + [FHIR]: https://hl7.org/fhir/ [`Patient`]: http://hl7.org/fhir/R4/patient.html [`m.file`]: https://spec.matrix.org/v1.14/client-server-api/#mfile + [Questionnaire]: https://www.hl7.org/fhir/questionnaire.html [canonical URL]: https://build.fhir.org/references.html#canonical [64 KiB event size limit]: https://spec.matrix.org/v1.14/client-server-api/#size-limits [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 [`Bundle`]: http://hl7.org/fhir/StructureDefinition/Bundle + [RFC 2045]: https://datatracker.ietf.org/doc/html/rfc2045#section-5 + [`POST /_matrix/media/v3/upload`]: https://spec.matrix.org/v1.14/client-server-api/#post_matrixmediav3upload + [RFC 6906]: https://datatracker.ietf.org/doc/html/rfc6906 From d7a27eac25c8ea5071da72f8c1f00fd82bc6b72f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 15 Jul 2025 10:44:34 +0200 Subject: [PATCH 4/5] Remove surplus spaces --- proposals/4302-fhir-resources.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/4302-fhir-resources.md b/proposals/4302-fhir-resources.md index ae86be1c865..73802593687 100644 --- a/proposals/4302-fhir-resources.md +++ b/proposals/4302-fhir-resources.md @@ -33,14 +33,14 @@ A new event type `m.fhir.resource` is introduced with the following properties i "content": { "canonical_url": "http://hl7.org/fhir/patient.html|4.0.1", "m.fhir.resource": { - "resourceType" : "Patient", - "name" : [{ - "use" : "official", - "given" : ["John", "James"], - "family" : "Doe" + "resourceType": "Patient", + "name": [{ + "use": "official", + "given": ["John", "James"], + "family": "Doe" }], - "gender" : "male", - "birthDate" : "1970-01-01", + "gender": "male", + "birthDate": "1970-01-01", // further properties as per the Patient schema }, "m.file": { From 9b23cc963bd8a91c5c37da1556abf332a89a544b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 15 Jul 2025 10:45:42 +0200 Subject: [PATCH 5/5] Use correct mimetype in example --- proposals/4302-fhir-resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4302-fhir-resources.md b/proposals/4302-fhir-resources.md index 73802593687..efb0cabaaa9 100644 --- a/proposals/4302-fhir-resources.md +++ b/proposals/4302-fhir-resources.md @@ -45,7 +45,7 @@ A new event type `m.fhir.resource` is introduced with the following properties i }, "m.file": { "url": "mxc://example.org/abcd1234", - "mimetype": "application/json", + "mimetype": "application/fhir+json", // further properties as per MSC3551 } }