FHIR Chat · R4B compatibilty · implementers

Stream: implementers

Topic: R4B compatibilty

---

Josh Mandel (Jan 24 2022 at 21:29):

From discussion here and reviewing our version compatibility rules, I'm concerned about the current approach to considering R4B as a "technical correction" and "minor version update" to FHIR R4. Why? We say at https://build.fhir.org/versions.html#versions:

• Major version "Increments every time a breaking change is made (see below)"
• Breaking changes "are changes that mean that previously conformant applications are no longer conformant to the updated specification"

I see much potential for "previously conformant" (i.e., R4-compatible) applications to break when pointed at an R4B server. For example:

• Parsing a code in CapabilityStatement.fhirVersion when discovering a server's capabilities (this element has a required binding to the codes at https://hl7.org/fhir/R4/valueset-FHIR-version.html has our published list of codes)

• Even clients following our rules for "wishing to maximize backwards compatibility" (which as worded sounds highly optional, not like a strict requirement for being considered "conformant"!) would only have advice about "dealing with content from a system supporting an unknown normative version" --- and presumably FHIR R4 is not a "normative version"

  • Querying a FHIR server in ways that could return new R4B resources or datatypes

    • e.g. Patient-everything or System-export" operations, or GET /_history or GET ? or various _include=*` invocations might suddenly return new resource types when submitted to an R4B server

  • Common client libraries are likely to crash when parsing unexpected resource types in response to previously-working queries like

Lee Surprenant (Jan 24 2022 at 23:17):

In our implementation, I'm currently thinking to force clients to request version 4.3.0 (by passing an Accept header with the fhirVersion=4.3 mime type parameter) in order to get back the new resource types from whole-system interactions like system-search, system-history, and $export.
I already implemented something like that for our CapabilityStatement (based on experience at connectathon).
If it works the way I expect, that would make the server mostly backwards-compatible. What it doesn't address is the fact we always apply the updated (4.3.0) constraints for all resource types...that could be "breaking" for some resource types, but these are really "corrections" and so I'm still hoping we can get R4 users to fix their stuff for these as well.

Lloyd McKenzie (Jan 25 2022 at 00:39):

90% of implementations will have no use for any of the changed resources. 9.9% will care only about the net new Subscription resources. Only .1% will care about the medication definition and EBM content. For systems that don't use anything that's changed, the change should be completely transparent.

Josh Mandel (Jan 25 2022 at 01:09):

I don't know whether these percentages are accurate, and I am not sure why they're relevant to the design question of what "compatible" means.

Josh Mandel (Jan 25 2022 at 01:10):

We don't say "bump major version when we expect xx% of applications will break"

Lloyd McKenzie (Jan 25 2022 at 02:09):

The systems that care about the net new things didn't use them in R4, so for them R4B is the only thing they care to implement. The systems that did implement R4 don't care about the new things in R4B with the possible exception of the Subscription changes. If introducing the Subscription changes means we can no longer consider R4B substitutable for R4, then we shouldn't have incorporated them...

Josh Mandel (Jan 25 2022 at 02:22):

My concern is that any new datatypes, new resources, or resources that have seen breaking changes will lead to compatibility problems; it's nothing specific to subscriptions or medications.

Lloyd McKenzie (Jan 25 2022 at 02:42):

The most likely place of breaking is in the enumerations for supported resources and FHIR versions. Old systems might well choke on those. Other than that, there should never be an instance of any of the resources shared in R4 that will ever contain one of the new resources defined or renamed in R4B - not as contained, not in an extension. There is no possible use-case where that would make sense. (And any system that's using the new resources is, by definition, one that must pre-coordinate with systems to ensure that they support R4B.) For any system that only cares about the stuff that only existed in R4, they can continue to use that stuff when communicating with an R4B system unchanged - and vice versa.

Josh Mandel (Jan 25 2022 at 02:58):

Again, there are FHIR operations such as search and history and export that can run at the server level; a client that knows how to parse the results of those operations today (e.g., using existing R4 libraries) is going to suddenly stop working if the server it is talking to suddenly "upgrades" to R4B (or a new server that it is introduced to support this new version).

Lloyd McKenzie (Jan 25 2022 at 03:12):

Search is only impacted if you're doing searches at the base resource level - which very few real clients do. And then, they'd only fail if the servers they were talking to had the new resources, which is also exceptionally unlikely. If you're talking to a test server, then yes, it's possible. If you're talking to a real server, the scenario is exceptionally unlikely. Same is true for export. If you're doing a full dump of a server, then you already know exactly what the server does before asking for an export.

Kevin Mayfield (Jan 25 2022 at 09:17):

I sort of agree with @Lloyd McKenzie
I don't think using R4B for Subscription services is much of a technical issue.

All the resources we would get would 'R4' posted to a R4B endpoint.

However I'm concerned around the number of meetings this would cause. We are already seeing fhir versioning becoming a major topic (.... and the more pressing issue of v2 to FHIR ignored)

Josh Mandel (Jan 25 2022 at 13:48):

It's possible we just need to update our versioning rules to allow for some kinds of breaking changes within a minor release -- I just don't want our reasoning about what is/isn't "breaking" to be based on how many systems will break. Of course, our choices about when to allow breakage could depend on this, but the definition of breakage shouldn't

Josh Mandel (Jan 25 2022 at 13:50):

For example, the fhirVersion ValueSet binding for CapabilityStatement doesn't seem to be a real world issue (presumably because real clients are not depending on receiving a valid capability statement at runtime, perhaps because applications have already developed flexibility here in response to the 4.0.1 release which would have surfaced brittle implementations).

Michele Mottini (Jan 25 2022 at 13:58):

real clients are not depending on receiving a valid capability statement at runtime

mhh, our client definitely depends on that

Josh Mandel (Jan 25 2022 at 14:18):

But do you depend on CapabilityStatement.fhirVersion being drawn from the required binding (https://hl7.org/fhir/R4/valueset-FHIR-version.html)?

Josh Mandel (Jan 25 2022 at 14:18):

That is the particular sense of "valid" that I had in mind here @Michele Mottini.

Michele Mottini (Jan 25 2022 at 14:29):

The R4 library will not be happy if it sees a value there that it does not recognize, it can be configured to ignore the error and leave fhirVersion empty - that I think would work

Josh Mandel (Jan 25 2022 at 14:40):

it can be configured to ignore the error and leave fhirVersion empty - that I think would work

It would work in the sense of "your application code used to be conformant to FHIR R4 and interoperate with R4 servers, but after the release of R4B you need to write new code updating library version or library configuration to interoperate with R4B servers." That's practically the definition of a breaking change. (To be clear, I'm not against breaking changes. I'm just against including them in a minor release given our current versioning rules.)

Josh Mandel (Jan 25 2022 at 18:15):

Also from @Gino Canessa it looks like R4B has added new options to the choice type for ActivityDefinition.subject[x] (subjectCanonical is new). Is this a known/desired change within our versioning rules?

Michele Mottini (Jan 25 2022 at 21:37):

I think it would work without changes, our code does not depend on having a value in fhirVersion and we set the library to ignore unknown enumeration values.
If either of those things were not true though we would have to change our client code to connect to a R4B server, that would be a huge pain

Lee Surprenant (Jan 25 2022 at 22:53):

I hit an interesting one today and just wanted to capture it here: DeviceDefinition

This one breaks due to the change in the underlying ProductShelfLife type. It was maturity level 0 in R4, so probably fine, but I wanted to be sure to capture/communicate it somewhere in case its an unexpected breakage (because I wasn't sure if its considered part of the "medication definition or EBM content")

Lloyd McKenzie (Jan 25 2022 at 23:09):

Hmm. That's definitely an issue. I'll bring it to the FMG

Lloyd McKenzie (Jan 25 2022 at 23:10):

We may end up requiring the medication resources to use ProductShelfLife2 or something in R4B so that DeviceDefinition is left alone.

Lee Surprenant (Jan 26 2022 at 01:41):

Is it possible to flip DeviceDefinition to an in-line BackboneElement that matches the R4 structure? That might be slightly cleaner than the ProductShelfLife2 approach given that in R5 you probably want the two aligned on the ProductShelfLife type.

Lloyd McKenzie (Jan 26 2022 at 04:05):

That's also an option. Not sure it causes any less or more issue for R4B->R5 transition though.

Rik Smithies (Jan 26 2022 at 11:59):

re the change to ProductShelfLife, it was for an R4B ballot comment (Lloyd's) to change a data type from Quantity to Duration - making it clear it is time related. It's a good change.
But I wonder if it may be pragmatic to put that change into R5, and back it out of R4B. Then there is no compatibility issue, no need to create a clone of the datatype or create a backbone, and then no need to put things back together again in R5. Otherwise things need to change, and then change again. Delaying the improvement wouldn't seem to hurt.

Lee Surprenant (Jan 26 2022 at 13:18):

the other ProductShelfLife change was the removal of ProductShelfLife.identifier

Lee Surprenant (Jan 26 2022 at 13:20):

Since PackagedProductDefinition is a new resource type, I don't think there are any backwards-compatibility concerns for that one, so to me it makes more sense for that to be as close to what its going to be in R5 as possible.

Lee Surprenant (Jan 26 2022 at 13:58):

Also from @Gino Canessa it looks like R4B has added new options to the choice type for ActivityDefinition.subject[x] (subjectCanonical is new). Is this a known/desired change within our versioning rules?

Just wanted to mention that this also applies to PlanDefinition.

Lee Surprenant (Jan 26 2022 at 13:59):

Do we want JIRAs for these 2 (the DeviceDefinition one and the ActivityDefinition/PlanDefinition one)?

Rik Smithies (Jan 26 2022 at 14:09):

@Lee Surprenant edit - yes ProductShelfLife had an identifier in R4, it was long gone by R4B but that is another change.

Josh Mandel (Jan 26 2022 at 22:32):

Thanks to @Grahame Grieve for pointing out where I went wrong: R4B as 4.3.0 is actually a major updated over 4.0.1 because the middle segment is the major version number. ("publication.major.minor[.patch]" is the format for these version numbers!) Therefore: breaking changes are allowed/expected.

Lee Surprenant (Feb 04 2022 at 14:02):

Lloyd McKenzie said:

Hmm. That's definitely an issue. I'll bring it to the FMG

@Lloyd McKenzie did you ever bring this to FMG?

Lloyd McKenzie (Feb 04 2022 at 14:57):

Jiras would be helpful, yes. We did talk about it, but didn't land it.

Lee Surprenant (Feb 05 2022 at 04:33):

opened FHIR#35962 and FHIR#31763

Lee Surprenant (Feb 18 2022 at 14:12):

Correction: the DeviceDefinition-related change request that I opened for R4B is FHIR-35961, 31763 was just something related to 35962

---

Last updated: Apr 12 2022 at 19:14 UTC