Stream: implementers
Topic: Versioning strategy for profiles
Keerthi M (Aug 26 2019 at 13:27):
Hi,
We are setting up some processes in place to handle versioning of profiles in our project. Basically we have multiple profiles and most of them are used by multiple applications. So when one application needs a breaking change in a profile, it breaks functionality in other applications. I have listed down here some approaches to handle this. Can you please suggest what the best practices are and if there is any other way we can go.
1. Create a new profile version with a new URL (something like patient-2) --> the application that needs this new profile will send the meta.profile in its resources. I understand that we need to be careful about also fixing references between profiles in this case.
2. Use canonical URL with version using the pipe token --> again here the application needs to send meta.profile in its resources. This seems to be very similar to approach 1. Only we will not have multiple copies of the Profile. Is this correct?
3. Packaging --> I understand that this is basically grouping related conformance resources together like a zip and sharing. I am not clear how we leverage this in our case. For example, if we have separate packages for the applications, all the data at the end is going to a common DB. How can data extraction happen? I mean which profile should be considered?
Looking forward to your support!
Michele Mottini (Aug 26 2019 at 13:34):
Different profiles should not cause breaking changes
Keerthi M (Aug 26 2019 at 13:45):
Hi, sorry, I meant each profile is used by multiple applications.
Lloyd McKenzie (Aug 27 2019 at 03:44):
Breaking changes between versions of profiles is certainly possible when the profiles are low-maturity. Ideally, you'll have a maturity scale where, at some point, you lock profiles (and value sets and other things) down and promise to maintain backward compatibility - such that if you make a breaking change, you have to use a new canonical URL. In the meantime though, distinguishing profiles by business version is completely reasonable. Applications should ideally comply with a particular IG version and that IG version will contain (and/or reference) specific profile versions. If you're receiving inbound data and don't know a priori what version of the IG a given source is using, then it's certainly helpful if the instances declare what profile version(s) they're valid against. However, in many cases, that's not something you can guarantee. The alternative is you need to check inbound instances against the various possibilities.
Lloyd McKenzie (Aug 27 2019 at 03:45):
Also note that well-defined profiles try hard not to prohibit extra data, so it's often possible to have instances that comply with multiple profiles even if they have different expectations.
Keerthi M (Aug 27 2019 at 06:30):
Many thanks for the response!
One question about using the canonical url with business version (using the pipe token)..
in STU3 i see that the meta.profile is of type URI. In R4 it is changed to canonical.
We are still currently on STU3. Can we still use the canonical URL with the pipe token in meta.profile of STU3? or is there any other way to handle this?
Lloyd McKenzie (Aug 27 2019 at 14:28):
Many tools will just treat the STU3 URI as a canonical as it will work just fine - but that's not guaranteed. There isn't any other way I'm afraid.
Mike Lohmeier (Jun 10 2021 at 14:30):
Resurrecting an old thread here but what if it's the norm to version profiles? In my case, we're using a FHIR API as part of a bigger platform that powers all our internal and external apps. There's an API version number associated with the platform that we can cross cut into FHIR using the business version but there doesn't seem like a way to iterate on IG, Profiles and StructureDefinition safely. Ideally, we could version our IGs in a semantic fashion and allow every client to pin to a semantic version and get both binary and behavior that matches the version requested.
For example, in v1.0.0 of our platform API we might add field A to patient. In v1.1.0 we might add field B to patient. Our single FHIR API implementation should be smart enough to serve up IGs for both v1.0.0 and v1.1.0 and we can have clients pinning to either version at any time.
Is there any facility to have a client specify business version in a request similar to the fhirVersion Accept header?
Lloyd McKenzie (Jun 10 2021 at 14:50):
You can't generally specify what profile you want when you're requesting data. A system will express all data it has for a resource that you're allowed to see - and that interface will comply with whatever profiles (and profile versions) it complies with.
Lloyd McKenzie (Jun 10 2021 at 14:51):
Typically profiles are all up-versioned with each new release of the implementation guide they're part of (whether the specific profile has changed or not).
Mike Lohmeier (Jun 10 2021 at 14:58):
How do you guarantee clients won't break then? While most clients have no problems with minor version changes like adding a new field but it will break some clients.
Mike Lohmeier (Jun 10 2021 at 15:02):
A good example is an enum. If version 1.0.0 has an enum defined as A,B,C and version 1.1.0 has an enum defined as A,B,C,D we will break any client compiled against v1.0.0 when a value of D is returned.
Lloyd McKenzie (Jun 10 2021 at 15:10):
You won't have any enums that can change for versions of a profile unless you're talking about an extension. Any 'code' elements (e.g. Patient.gender) are tied to the version of FHIR you're using and can't be changed by profile - at least not beyond constraining them. For extensions, clients would need to be robust against code value sets changing - or the Extension data type should be Coding or CodeableConcept to encourage such robustness.
You can choose to expose different endpoints for different clients and keep them frozen to particular profile versions if you wish, but that's the only way to control what profiles will be exposed by the endpoint.
Mike Lohmeier (Jun 11 2021 at 14:36):
hmm thanks. We should be able at the infrastructure level expose a version number of the API in the URL and have the same implementation servicing all versions. It's a bit clunky but it works. I really don't want to pass the buck of reverse compatibility to all clients and not allow clients to pin to a business version.
Last updated: Apr 12 2022 at 19:14 UTC
