Merge d293672220 into e9f0f31d27
Johannes Marbach
3 days ago
committed by
GitHub
commit
a4a5b49d9c
@ -0,0 +1,185 @@
|
||||
# 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 generic medical forms. This type defines
|
||||
several fields such as an *optional* `title` property containing a human readable 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.
|
||||
|
||||
Profiles can extend either resource types or other profiles, meaning it is possible to build chains
|
||||
of profiles. Both resource types and profiles are described via [`StructureDefinition`]s which are
|
||||
uniquely identified by their [canonical URL].
|
||||
|
||||
``` json5
|
||||
{
|
||||
// This is the profile ISiKFormularDefinition v5.0.0, created by gematik GmbH
|
||||
"resourceType": "StructureDefinition",
|
||||
"id": "ISiKFormularDefinition",
|
||||
"url": "https://gematik.de/fhir/isik/StructureDefinition/ISiKFormularDefinition",
|
||||
"version": "5.0.0",
|
||||
"publisher": "gematik GmbH",
|
||||
// It extends the base type Questionnaire from FHIR v4.0.1
|
||||
"type": "Questionnaire",
|
||||
"fhirVersion": "4.0.1",
|
||||
// It is based directly on the base type without intermediary profiles
|
||||
"baseDefinition": "http://hl7.org/fhir/StructureDefinition/Questionnaire",
|
||||
// It changes the base type, among others, by making the title field mandatory
|
||||
"differential": {
|
||||
"element": [{
|
||||
"id": "Questionnaire.title",
|
||||
"min": 1,
|
||||
"mustSupport": true,
|
||||
...
|
||||
}, ...]},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
While the above example is trivial, the customisations achievable via profiling can be extensive. As
|
||||
a result, it is crucial for implementations to understand what profiles are being used when
|
||||
exchanging data.
|
||||
|
||||
## 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 `Questionnaire`s, 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 `QuestionnaireResponse`s into
|
||||
a hospital'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 mitigated to some extent if FHIR resources were inlined into Matrix events.
|
||||
However, serialized resources contain only limited information about the underlying
|
||||
`StructureDefinition`. Most importantly the base resource type is missing, making it difficult for
|
||||
implementations that support a base type but not a specific profile to fall back in a reasonable
|
||||
way. Furthermore, inlining isn't always possible due to the [64 KiB event size limit] and no
|
||||
suitable event type or content block exists, as of writing.
|
||||
|
||||
## Proposal
|
||||
|
||||
To enable the compatible and efficient exchange of FHIR resources in either inline or file form, a
|
||||
new event type `m.fhir` is introduced. This type mandates the following properties in `content`:
|
||||
|
||||
- `m.fhir.structure_definition` (object, required): Information about the resource's
|
||||
`StructureDefinition`.
|
||||
- `url` (string, required): The [canonical URL] of the most specific `StructureDefinition`
|
||||
describing the resource. This is equivalent to [`StructureDefinition.url`].
|
||||
- `version` (string, required): The version of the `StructureDefinition`. This is equivalent to
|
||||
[`StructureDefinition.version`].
|
||||
- `type` (string, required): The `StructureDefinition`'s base type. This is equivalent to
|
||||
[`StructureDefinition.type`].
|
||||
- `fhir_version` (string, required): The version of the FHIR specification on which the
|
||||
`StructureDefinition` is based. This is equivalent to [`StructureDefinition.fhirVersion`].
|
||||
- `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.
|
||||
|
||||
``` json5
|
||||
{
|
||||
"type": "m.fhir",
|
||||
"content": {
|
||||
// Metadata to help identify the resource
|
||||
"m.fhir.structure_definition": {
|
||||
"url": "https://gematik.de/fhir/isik/StructureDefinition/ISiKFormularDefinition",
|
||||
"version": "5.0.0",
|
||||
"type": "Questionnaire",
|
||||
"fhir_version": "4.0.1",
|
||||
},
|
||||
// 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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `url` and `version` properties, on the one hand, allow implementations with support for the
|
||||
particular profile to activate dedicated display or processing logic. The `type` and `fhir_version`
|
||||
properties, on the other hand, enable implementations *without* support for the specific profile to
|
||||
offer fallback behaviour if they have generic support for the resource's base type.
|
||||
|
||||
## Potential issues
|
||||
|
||||
FHIR includes generic resources such as [`Bundle`] which wrap other resources. The metadata in
|
||||
`m.fhir.structure_definition` will not help clients understand the wrapped content without
|
||||
downloading it in these cases. Dedicated event types or further metadata fields 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 and profiles this doesn't appear practical, however.
|
||||
|
||||
[RFC 2045] allows MIME types to include modifying parameters. The contents of
|
||||
`m.fhir.structure_definition` could, therefore, be included alongside the media type[^1].
|
||||
|
||||
``` http
|
||||
Content-type: application/fhir+json; url="https://gematik.de/fhir/isik/StructureDefinition/ISiKFormularDefinition"; ...
|
||||
```
|
||||
|
||||
This would allow reusing the `m.file` message type but leaks metadata 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.structure_definition`. As a minimal defense, clients SHOULD
|
||||
sanity-check the size of the downloaded file by issuing a HEAD request and refuse to automatically
|
||||
download large files without explicit user consent.
|
||||
|
||||
## Unstable prefix
|
||||
|
||||
While this MSC is not considered stable, the following identifiers should be used:
|
||||
|
||||
- `m.fhir` → `de.gematik.msc4302.fhir`
|
||||
- `m.fhir.structure_definition` → `de.gematik.msc4302.fhir.structure_definition`
|
||||
- `m.fhir.resource` → `de.gematik.msc4302.fhir.resource`
|
||||
|
||||
Note that `m.file` has its own prefixing requirements as per [MSC3551].
|
||||
|
||||
## 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.
|
||||
|
||||
[FHIR]: https://hl7.org/fhir/
|
||||
[`Questionnaire`]: http://hl7.org/fhir/StructureDefinition/Questionnaire
|
||||
[`ISiKFormularDefinition`]: https://gematik.de/fhir/isik/StructureDefinition/ISiKFormularDefinition
|
||||
[`StructureDefinition`]: https://build.fhir.org/structuredefinition.html
|
||||
[canonical URL]: https://build.fhir.org/references.html#canonical
|
||||
[`m.file`]: https://spec.matrix.org/v1.14/client-server-api/#mfile
|
||||
[`QuestionnaireResponse`]: http://hl7.org/fhir/StructureDefinition/QuestionnaireResponse
|
||||
[64 KiB event size limit]: https://spec.matrix.org/v1.16/client-server-api/#size-limits
|
||||
[`StructureDefinition.url`]: https://build.fhir.org/structuredefinition-definitions.html#StructureDefinition.url
|
||||
[`StructureDefinition.version`]: https://build.fhir.org/structuredefinition-definitions.html#StructureDefinition.version
|
||||
[`StructureDefinition.type`]: https://build.fhir.org/structuredefinition-definitions.html#StructureDefinition.type
|
||||
[`StructureDefinition.fhirVersion`]: https://build.fhir.org/structuredefinition-definitions.html#StructureDefinition.fhirVersion
|
||||
[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
|
||||
Loading…
Reference in New Issue