Proposed Breaking changes for FHIR R4

According to the FHIR maturity model that is part of the FHIR development process, we must consult the community if we are going to make breaking changes to artefacts that are labelled level 4 or 5 maturity (though there’s some lack of clarity as to what exactly is a breaking change, and what the right process should be).

At the recent meeting in San Diego, a number of breaking changes to maturity 4/5 resources were proposed, and we are seeking feedback on these:

  • Rename ValueSet.compose to ValueSet.definition (Vocab)
  • Question on the use of related types with Observation (OO)
  • Proposal to adopt GitHub Flavored Markdown (FHIR-I)

In addition, while we are consulting, we are seeking feedback on an additional change:

  • Proposal to remove ImagingManifest (II)

Each of the changes is described below, along with the proposed justification. If you have already implemented systems that will be impacted by these changes, and you’d like to have your say, please send an email to by Friday 20th October that details your implementation, the impact the change will have, and your opinion about the change.

Note: if you don’t have an actual implementation, and you still have an opinion, we’d still like to hear it – you can let us know through one of our normal channels (see

Renaming ValueSet.compose

ValueSet.compose is a verb — “compose the value set this way”, but that’s not language that connects with the wider community as well as ValueSet.definition would – “this is the definition of the value set content” (which is the “Content Logical Definition”) in the Vocab work group’s wider value set work). Also, ValueSet.definition matches ValueSet.expansion grammatically. Finally, ValueSet.compose overlaps in name with the $compose operation.

For these reasons, the work group would like to rename .compose to .definition. There’s no other semantic changes – it’s just a straight rename, to reduce confusion.

Note that ValueSet is planned for normative in R4 – there won’t be any other chance to make this change.

Use of Observation.related and types

Are you using Observation.related? how? The Orders and Observations Work considering removing .related and replacing it with:

  • member : Observation 0..*   type: Reference(Observation)
  • derived: Observation 0..*  type: Reference(Observation)

The other things related does would be relegated to extensions, or to the Provenance resource. The task proposing this (GForge #10118) was discussed at the Sept WGM by the Orders and Observations Work Group and is the direct result of internal FHIR methodology review and discussion which resulted in a proposal to substantially change the .related structure. This would simplify the structure of Observation, but the OO work group has been hesitant to make a significant change without meaningful implementer input.

Because our past attempts to get implementer feedback by reaching out to the FHIR community did not result in any response, the work group has deferred this tracker several times. As the Observation resource approaches normative status, there is increasing concern regarding making substantive changes. Implementer feedback is sought regarding whether that perceived benefits of this proposal is outweighed by the costs it imposes on implementation.

Adopting GitHub Flavored Markdown

Currently, the markdown data type specifies that the content is Gruber’s original markdown syntax, with an STU note soliciting feedback about adopting CommonMark instead. Feedback on this has generally been in favor of adopting commonmark, except that it doesn’t support tables, and it allows raw HTMlL. The community has indicated a strong preference for GitHub Flavored Markdown (GFM), and we propose to adopt this as a replacement. Note that the table extension in GFM are likely to find their way into commonmark, which would mean that we’d be using CommonMark with a profile that says ‘no HTML’

In practice, this will mean updating some existing code – e.g. a different markdown processing engine, and different generation, though the markdown syntaxes are somewhat compatible, and markdown degrades gracefully anyway.

Note, again, that the markdown data type is slated to be normative next time, so there’ll be no more opportunity to make this change. (though we could settle for pure CommonMark if the GFM extensions are brought into CommonMark – that would be a non-substantiative change). For further discussion, see

Proposal to remove ImagingManifest

The II committee (joint between DICOM and HL7) would like to remove the ImagingManifest resource. It’s a little hard for most implementers to differentiate between ImagingStudy and ImagingManifest, and the DICOM use cases for which ImagingManifest was defined (XDS-I) have been replaced by MHD-I which uses WIA (Web Image Access), leaving the use case for ImagingManifest somewhat obscure.

Hence the proposal is to remove ImageManifest and ensure that ImagingStudy can meet the identified needs.

Note that this is not a change that affects a maturity >=4 resource, so community consultation is not needed. However the committee asked for wider feedback. For further discussion, see