matrix-spec-proposals/proposals/4302-fhir-resources.md

MSC4302: Exchanging FHIR resources via Matrix events

A brief abstract of FHIR, resources and profiles

FHIR (pronounced "fire") is a globally established standard for the digital exchange of healthcare-related information. The base building block of FHIR are so-called resources. Resources have a type that defines their base schema. This schema can be further customised through one or more profiles.

As an example, Questionnaire is the resource type for medical forms that can be used for various purposes. This type defines several fields such as an optional title property containing a human friendly name for the form. ISiKFormularDefinition, in turn, is a profile on Questionnaire created by Germany's national health agency, gematik, for use within hospitals. It customises the schema of Questionnaire in several ways, such as making title required rather than optional.

Both resource types and profiles can be uniquely identified by their canonical URL.

The problems of using FHIR resources in Matrix

FHIR resources can be serialised into JSON or XML which can be transmitted via the m.file message type with a MIME type of application/fhir+json or application/fhir+xml. However, the generic MIME type doesn't let clients understand what resource is contained in the file without downloading it. This is suboptimal because clients may want to apply special display logic for certain resource types and profiles. Using the example of Questionnaires, clients may want to render the resource as an interactive form for the user to fill out and send back a QuestionnaireResponse resource.

Similarly, clients that connect external systems to Matrix may want to automatically process certain resources. For instance, an anamnesis bot may want to export received QuestionnaireResponses into a surgery's patient management system. Again, the generic MIME type forces such a client to download the file to determine if it is indeed a QuestionnaireResponse.

These problems would be obliterated if FHIR resources were inlined into Matrix events. However, this isn't always possible due to the 64 KiB event size limit. Additionally, no suitable event type or content block exists, as of writing.

Proposal

To enable the efficient exchange of FHIR resources in either inline or file form, a new event type m.fhir.resource is introduced. This type mandates the following properties in content:

• canonical_url (string, required): The resource's canonical URL, that is the globally unique identifier defining its base schema. MAY contain a version suffix separated by | as per the FHIR specification.
• profiles: (array of strings): The canonical URLs of the profiles the resource conforms to (if any). The order of elements in the array is arbitrary, similar to FHIR's own Meta.profile property.
• m.fhir.resource (object, required if m.file is missing): The serialised JSON if it fits within the 64 KiB event size limit.
• m.file (object, required if m.fhir.resource is missing): An MSC3551 content block describing an uploaded JSON or XML serialisation of the resource if it is too large to be inlined.

{
  "type": "m.fhir.resource",
  "content": {
    // Metadata to help identify the resource
    "canonical_url": "http://hl7.org/fhir/StructureDefinition/Questionnaire|4.0.1",
    "profiles": [
      "https://gematik.de/fhir/isik/StructureDefinition/ISiKFormularDefinition|5.0.0"
    ],
    // Either: The resource in inline form
    "m.fhir.resource": {
      "resourceType": "Questionnaire",
      "title": "Dr. Dre's anamnesis questionnaire for new patients",
      // further properties as per the questionnaire's schema
    },
    // Or: A file representing the resource
    "m.file": {
      "url": "mxc://example.org/abcd1234",
      "mimetype": "application/fhir+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

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¹.

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

Malicious clients could attempt to trick other clients into automatically downloading files by faking the metadata in m.fhir.resource events. As a minimal defense, clients SHOULD sanity-check the size of the downloaded file by issuing a HEAD request and refuse to download large files without explicit user consent.

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.

---

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. ↩︎