Stream: conformance
Topic: versioning profiles
Simone Heckmann (Sep 29 2018 at 21:31):
With the arrival of the new packaging feature in Simplifier, we have reopened the discussion of how to handle versioning of profiles.
The precise use case is that we are maintaining national profiles, that are still immature, so they we expect to have occational breaking changes in the future but people are already starting to derive their profiles from our profiles and need a way to be able to reference a stable version.
Packages give us a way to do this. but the question we're still undecided about is whether we also need to maintain version numbers in the canonical urls, e.g. .../Patient-core/1.0 followed by .../Patient-core/2.0 in the next release.
The only reason (we're aware of) why we would want to do this is that it allows an instance of a resource to calim conformance to a specific version of a profile.
However, it's a big effort to maintain this (just imagine having to update all references to Patient in your IG/package...)
So the question is:
1. What are good reasons why instances need version specific profile.meta references?
2. Are there reasons why they shouldn't ?
3. Why was the use of canonical ruled out for profile.meta, that would have allowed an optional addition of the version in a pipe-separated notation such as .../Patient-core|2.0?
4. How are other IG authors handling this?
Lloyd McKenzie (Sep 29 2018 at 21:34):
Erk. Um, I don't know why meta.profile doesn't allow canonical. I know I've got implementation guides that use it that way...
Lloyd McKenzie (Sep 29 2018 at 21:35):
Certainly wanting your profile reference to be version-specific is a reasonable thing to want. @Grahame Grieve, is this something that would be an allowed change in a future version or are we now stuck?
Patrick Werner (Sep 29 2018 at 21:46):
i can see benefits for both ways: specifying the profile including the version, and without.
With uri as profile datatype in meta you can't do both. With canonical as profile dataType this would be possible and much easier.
Simone Heckmann (Sep 29 2018 at 21:46):
"Certainly wanting your profile reference to be version-specific is a reasonable thing to want."
@Lloyd McKenzie , can you give me some reasons why?
Lloyd McKenzie (Sep 29 2018 at 21:51):
Because there's no expectation that different versions of a profile will impose the same constraints or be compatible
Lloyd McKenzie (Sep 29 2018 at 21:52):
So when you declare conformance, you want to be specific.
Lloyd McKenzie (Sep 29 2018 at 21:52):
But you don't necessarily want the canonical URL to change.
Simone Heckmann (Sep 29 2018 at 21:59):
Why is it important for the client to declare version specific conformance?
Couldn't the instance by chance still be conformant with a newer version even if a breaking change has been made?
(Like a newer version has added a requirement that has already been voluntarily satisfied by the client implementation).
Should a server reject a resource solely based on version mismatch in the declaration even if the resource validates against the server's requirements?
Should servers rely on a client's conformance claim without running validations against their own profiles?
Lloyd McKenzie (Sep 29 2018 at 22:02):
Client declaration gives a hint as to what validation a server should perform. It's costly for servers to validate against all possible profiles - or even all possible versions. A client declaration isn't an indication of everything they're conformant with, but is an indication of what they believe they're conformant with that they believe recipients are likely to care about/use
Simone Heckmann (Sep 29 2018 at 22:06):
Why would a server support more than one version of a profile at the same time?
Simone Heckmann (Sep 29 2018 at 22:09):
I‘m not saying that it shouldn’t, I just don’t see a real world use case that’s 80% enough to convince me of the necessity for versioned canonicals (especially considering the pain that comes with them)
Lloyd McKenzie (Sep 29 2018 at 22:14):
Servers support multiple versions because the clients don't all move at the same time
Lloyd McKenzie (Sep 29 2018 at 22:14):
I've got a couple of clients already doing exactly that.
Simone Heckmann (Sep 29 2018 at 22:47):
Couldn‘t this be addressed by attempting validation against the preferred version and - if that fails - try any supported older version before refusing the resource?
Simone Heckmann (Sep 29 2018 at 22:48):
Do you have an example of an IG that uses versioned canonicals?
Simone Heckmann (Sep 29 2018 at 22:50):
Is there any tooling for publishing versioned canonical IGs or is that manual labor?
Lloyd McKenzie (Sep 29 2018 at 23:41):
No public IGs. Two private ones. The server doesn't want to validate against more than one version. It wants the client to tell it what it's claiming and then to check that and process it or reject it. There could be 3 or 4 versions in use at any given time.
Martijn Harthoorn (Sep 30 2018 at 08:21):
One of the problems of profile (canonical) versioning is that profiles don't live in isolation. And once resources start conforming (meta.profile) to individual versioned profiles, they will also have to start versioning all references.
Martijn Harthoorn (Sep 30 2018 at 08:23):
Profiles can evolve at different speeds. And so it's very easy to create incompatible round trips. Something now suddenly the client will have to solve.
Martijn Harthoorn (Sep 30 2018 at 08:24):
And they won't
Martijn Harthoorn (Sep 30 2018 at 08:28):
And a resource is likely to conform to a range of profile versions that are backwards compatible. But I don't see resources having semver ranges and wildcards in their url.
Lloyd McKenzie (Sep 30 2018 at 11:26):
Generally the dependencies are managed at the IG level, not the profile level. And IG relationships are always version -specific. Profiles inherit their version from the IG they're released in.
Stefan Lang (Sep 30 2018 at 11:47):
Even if they didn't change since the previous IG version?
We currently do the same for the German base profiles, but doing this manually, including changing all the IG internal references to the profiles (e.g. targetProfile), is a lot of work and prone to error. Therfor the question about tooling.
Martijn Harthoorn (Sep 30 2018 at 12:07):
The power of the packaging draft we have now is that it uses npm SemVer ranges to manage backward compatibility. We've have implemented this in our package manager client. And sofar the results are promising. This issue is not new. It has been solved already in various degrees of success in the 'bigger' programming languages. nuget in C#, npm in js. etc. Just replace profile with 'class'.
Simone Heckmann (Sep 30 2018 at 12:31):
The problem is: we have to decide now whether we version our URLs or not and whatever we decide, we will have to maintain it and live with it forever. So we really would like to hear as many opinion and experiences as possible.
IMO the ideal solution would have been the canonical notation which makes the use of versions optional (unless a profile indicates otherwise) and removes the requirement to maintain the versioned URLs independently or struggle with reference integrity.
But it seems this option is out of the game. Was it a conscious decision or an oversight that profile.meta is not canonical?
Lloyd McKenzie (Sep 30 2018 at 12:47):
Yes. The profiles get versioned whether they changed or not (and whether the changes were substantive or breaking or not)
Lloyd McKenzie (Sep 30 2018 at 12:49):
It's not mandatory to do that when you use the IG publisher, but I believe all of the HL7-published IGs do so and all the clients I've worked with have used that approach. It also ties into the package-baged publication approach for IGs
Simone Heckmann (Sep 30 2018 at 13:09):
I'm not sure if we aren't artifically lowering interoperability when servers expect a certain version, but get another and reject it, when in fact the profiles didn't change at all. (...or maybe just added a new required field, that the client has always been populating anyway)
I'd much rather have the server to at least make an attempt to validate the instance and then decide upon the result wether to reject or accept it.
I would also expect (many?/most?) servers to have additional constraints to whatever profile they support (like e.g. a maximum number of addresses per Patient or additional required fields) so it would have to test the instances anyway regardless of their conformance claim.
If servers don't validate incoming resources but simply try to run them through whatever processing they do, the processing might either succeed or fail. So why not just try regardless of profile version and accept or reject depending on the outcome?
Stefan Lang (Sep 30 2018 at 13:12):
I think that openness may be one valid behavior, while in other cases you definitely want to bind your instance to an explicit version of a profile.
Stefan Lang (Sep 30 2018 at 13:13):
canonical with pipe notation would (would have?) allow(ed) that
Simone Heckmann (Sep 30 2018 at 13:15):
True, I'm just not sure yet, how "corner" these cases are and if they could not be solved with a version-extension on profile.meta (assuming that pipe notation is out) and not burden the rest of the world (both IG authors and implementers) with this added complexity.
Stefan Lang (Sep 30 2018 at 13:23):
Agreed on a core extension as a possible solution for the instance profile version claim.
Another issue in this context is that derived profiles definitely need to be able to tell the exact version of the profile they derive from. Everything may result in any kinds of strange behavior.
SD.baseDefinition is of type canonical, so that's fine from a spec point of view. Maybe the importance of using [URL]|[version] here should be pointed out somewhere.
Asking the Toolsmith: @Michel Rutten Does/will Forge support automagically adding "|version" into baseDefinition?
Also the reference server need to support that
Lloyd McKenzie (Sep 30 2018 at 13:51):
I agree that servers requiring profile declaration of any sort isn't super-friendly, but it's a relatively cheap thing for clients to do and it means a considerable saving on the server side. It does mean that servers have to be in a situation where they can demand changes to a client instance - and that won't always be the situation.
Simone Heckmann (Sep 30 2018 at 14:00):
@Stefan Lang but that's exactly the problem that packaging solves quite neatly. The only thing packages don't solve is the declaration in the instance...
Stefan Lang (Sep 30 2018 at 14:01):
True. If everybody uses packages ...
Stefan Lang (Sep 30 2018 at 14:10):
Still, as far as I understand it, once a package is loaded into a FHIR server, every profile stands on it's own.
The FHIR server does not know anything about package versions (...if they are not identifical to SD.version ...). Sound like an indeterminancy here?
Martijn Harthoorn (Sep 30 2018 at 14:19):
In most cases a fhir server will have an implicit a "scope" or "context" that has several packages. I can imagine that such a context deserves it's own endpoint. Because that is a much more natural language for a FHIR client and far less hassle.
Martijn Harthoorn (Sep 30 2018 at 14:20):
Client software having to keep track of canonical URL versions is hard to enforce and error prone.
Martijn Harthoorn (Sep 30 2018 at 14:26):
Because it's the client defining it's own rules on the server.
Ewout Kramer (Sep 30 2018 at 14:30):
Yes, Grahame and I were just shortly discussing this: it is true that the complexity is now on the client. The instance the client pushes would have to be explicit about the version of the structuredefinition. But it does not stop there. That structuredefinition should then also be explicit about the SDs it itself references. So, when uploading a StructureDefinition, the client should be explicit about the versions in the canonical references, if multiple can exist on the server. That does not sound attractive. One solution is that when you POST a StructureDefinition, the server knows about the versioning context and resolves it at that early point. Another would be that you somehow specify the context the moment you call $validate.
Simone Heckmann (Sep 30 2018 at 14:42):
Actually, I wasn't thinking about Clients posting SDs, I was thinking about Clients posting Resource Instances which conform to a specific version of a profile... e.g.: a Patient resource conforming to http://fhir.de/StructureDefinition/patient-de-basis in the version 0.8
Simone Heckmann (Sep 30 2018 at 14:43):
Right now, the client doesn't have a way of saying that it's 0.8
Stefan Lang (Sep 30 2018 at 14:43):
(apart from having the version as part of the SD's canonical url, that is ...)
Simone Heckmann (Sep 30 2018 at 14:44):
Yep. but as I understand it, the whole point of packaging is to avoid just that.
Ewout Kramer (Sep 30 2018 at 14:44):
Yes, but before that there was at least some entity that installed those structuredefinitions on the server - that's what I meant with "client" here. The moment you submit a set of conformane resources to a server, you could resolve all canonicals to make them explicit about the version they refer to.
Ewout Kramer (Sep 30 2018 at 14:45):
Right now, the client doesn't have a way of saying that it's 0.8
Patient.meta.profile= "http://mysource.org/fhir/mysd|0.8" you mean?
Simone Heckmann (Sep 30 2018 at 14:45):
Yes, we can't do that because meta.profile is of type uri, not canonical
Stefan Lang (Sep 30 2018 at 14:46):
I mean "http://mysource.org/fhir/mysd/0.8" or similar, since meta.profile does not allow for "|"
Ewout Kramer (Sep 30 2018 at 14:46):
well, uri is a superset of canonical, so you can.
Simone Heckmann (Sep 30 2018 at 14:46):
uh? is it?
Stefan Lang (Sep 30 2018 at 14:46):
But does any server support that?
Simone Heckmann (Sep 30 2018 at 14:47):
I thought we had introduced canonical because uri didn't allow pipes....?
Stefan Lang (Sep 30 2018 at 14:47):
"The canonical type differs from a uri in that it has special meaning in this specification, and in that it may have a version appended, separated by a vertical bar (|)."
Stefan Lang (Sep 30 2018 at 14:47):
That implies url does not allow pipe
Ewout Kramer (Sep 30 2018 at 14:51):
That bit of text is from R4, where Meta.profile is a canonical, so that's not a problem. Note that we should not forbid a pipe in a url - but there is already a ballot comment to fix that formulation.
Simone Heckmann (Sep 30 2018 at 14:52):
Nope: http://build.fhir.org/resource.html#Meta it's uri
Ewout Kramer (Sep 30 2018 at 14:53):
sound like black magic:
pasted image
Ewout Kramer (Sep 30 2018 at 14:54):
;-) Are you sure you are looking at build.fhir.org?
Martijn Harthoorn (Sep 30 2018 at 14:54):
canonical: A URI that refers to a canonical URI. The canonical type differs from a uri in that it has special meaning in this specification, and in that it may have a version appended, separated by a vertical bar (|). Note that the type canonical is not used for the actual canonical URls that are the target of these references, but for the URLs that refer to them, and may have the version suffix in them. Canonical URLs may also have #fragment references
Simone Heckmann (Sep 30 2018 at 14:54):
Ewout Kramer (Sep 30 2018 at 14:54):
It's not updated here: 2.26.3.7
Ewout Kramer (Sep 30 2018 at 14:54):
yep.
Stefan Lang (Sep 30 2018 at 14:55):
That's an ouch ...
Ewout Kramer (Sep 30 2018 at 14:55):
nah, that's a gForge issue.
Stefan Lang (Sep 30 2018 at 14:55):
Is it already?
Simone Heckmann (Sep 30 2018 at 14:57):
Ok, can we reset this conversation, please :D
Grahame Grieve (Sep 30 2018 at 14:57):
the authortitative source for Meta.profile is that able below the one Simone quotes above. that's a typo we can just fix.
Ewout Kramer (Sep 30 2018 at 14:58):
Grahame Grieve (Sep 30 2018 at 14:58):
you beat Lloyd
Stefan Lang (Sep 30 2018 at 14:58):
and me :P
Ewout Kramer (Sep 30 2018 at 14:59):
Well, at least now everyone reading this is aware of this subtle R4 change ;-)
Simone Heckmann (Sep 30 2018 at 14:59):
Sooooo....about versiones URLs.... anyone still care about those? Or can we all go home now?
Simone Heckmann (Sep 30 2018 at 15:00):
(regarding R4 of course).
You'll probably still need them to work around the absence of "canonical" in STU3...
Stefan Lang (Sep 30 2018 at 15:00):
If the reference servers support pipe notation here, I'm completely happy.
Stefan Lang (Sep 30 2018 at 15:01):
STU3 is sooooo 2018 ...
Ewout Kramer (Sep 30 2018 at 15:02):
This was possible in STU3 too, but we didn't call it out explicitly - that's one of the reasons we introduced "canonical". You don't have to read the details description of a property to see you can use it logically as a canonical reference. In STU3 you had to dive into the description to see that.
Ewout Kramer (Sep 30 2018 at 15:03):
@Stefan Lang - guilty as charged, our server doesn't yet.
Grahame Grieve (Sep 30 2018 at 15:03):
where do we need to support it?
Ewout Kramer (Sep 30 2018 at 15:05):
We don't yet resolve |version to the correct version of a conformance resource. (e.g. in Meta.profile)
Grahame Grieve (Sep 30 2018 at 15:05):
when do we resolve?
Grahame Grieve (Sep 30 2018 at 15:05):
behind the $valdiate operation - any other time?
Ewout Kramer (Sep 30 2018 at 15:06):
yes, snapshot time
Grahame Grieve (Sep 30 2018 at 15:06):
I'll add getting this sorted to my list of things to do
Simone Heckmann (Sep 30 2018 at 15:09):
@Lloyd McKenzie do you have any plans to migrate from hardcoded versioned urls to canonical versioned urls in the future, or do you still see advantages in hardcoding them?
Grahame Grieve (Sep 30 2018 at 15:10):
both models will continue going forward
Ewout Kramer (Sep 30 2018 at 15:11):
I guess the same holds true for valuesets.
Grahame Grieve (Sep 30 2018 at 15:11):
y
Lloyd McKenzie (Sep 30 2018 at 15:34):
I use canonical versioned urls
Michel Rutten (Sep 30 2018 at 15:38):
@Stefan Lang
Does/will Forge support automagically adding "|version" into baseDefinition?
Currently not. Do you think we should address this?
Patrick Werner (Sep 30 2018 at 15:39):
yes, that would be nice
Stefan Lang (Sep 30 2018 at 15:40):
Definitely. For those deterministic guys like me ;)
Stefan Lang (Sep 30 2018 at 15:43):
Another place where the servers will have to support pipe notation then, also @Ewout Kramer @Grahame Grieve
Michel Rutten (Sep 30 2018 at 15:44):
OK, good to know. I will definitely look into this when we start working on Forge for R4 (after final FHIR R4 publication). Do you also need this for STU3?
Simone Heckmann (Sep 30 2018 at 16:03):
Does it make sense to append the version to all canonical references when creating a package?
Simone Heckmann (Sep 30 2018 at 16:04):
To me, it feels redundant, but I know that Stefan disagrees :)
Stefan Lang (Sep 30 2018 at 16:04):
I do :D
Stefan Lang (Sep 30 2018 at 16:05):
It's just not deterministic.
How can I specify a clear derived profile when I don't say which profile exactly I'm deriving from?
Simone Heckmann (Sep 30 2018 at 16:06):
That brings us back to the point where everyone has to deal with the added complexity simply because we want to satisfy those who don't use packages.
Stefan Lang (Sep 30 2018 at 16:06):
And I don't see how packaging (in it's current state) would help here, since the FHIR server doesn't know about packages ... at least not mandatory
Martijn Harthoorn (Sep 30 2018 at 16:09):
It would really help if there is a 'standard' way of describing how a FHIR server can conform to a package, a set of package or an IG. In my slowly evolved thought process around packages, I now call that a Context.
Martijn Harthoorn (Sep 30 2018 at 16:09):
Which is basically a list of package references.
Martijn Harthoorn (Sep 30 2018 at 16:09):
And which includes the indirect package dependencies.
Martijn Harthoorn (Sep 30 2018 at 16:10):
The best part is that a single package itself conforms to the definition of a context.
Stefan Lang (Sep 30 2018 at 16:11):
So each resource from a package would have a reference to that context attached somehow?
Would that also work without a FHIR server (there are people who use FHIR file based)?
Like an extension referring to the context in each SD?
Simone Heckmann (Sep 30 2018 at 16:20):
Would it make sense to have the packaging-tool automatically update all canonical resources to version specific resources?
(Whatever the versions of the resources are at the time of packaging?)
Stefan Lang (Sep 30 2018 at 16:24):
Right, that would be great. Some preprocessing to add the version within the SD right before publishing (aka packaging)
Michel Rutten (Sep 30 2018 at 16:24):
@Simone do you mean update all canonical resource references?
Simone Heckmann (Sep 30 2018 at 16:25):
I'm afraid so
Michel Rutten (Sep 30 2018 at 16:26):
So IIUC, you'd like to explicitly inject |version into all unversioned canonical urls in all profiles (all conformance resources?) in the package?
Simone Heckmann (Sep 30 2018 at 16:26):
Although: In fact only those targeting resources in the same package
Michel Rutten (Sep 30 2018 at 16:27):
I'm somewhat reluctant in that providing this feature could be perceived as encouraging users to do this...
Michel Rutten (Sep 30 2018 at 16:27):
Maybe tuck it away in an advanced menu option or something.
Simone Heckmann (Sep 30 2018 at 16:28):
Why would we want to discourage it?
(Which brings us back to the question we started with): What are the pros/cons of explicit references?
Martijn Harthoorn (Sep 30 2018 at 16:34):
Personally I am against explicit version referencing, exactly because you would need tooling to bulk-fix stuff. And conceptually it does the exact same thing as defining a context. Except that now the client tools need to be aware of it - and fix it with each update. And there won't be tools bulk-fixing the client software.
Martijn Harthoorn (Sep 30 2018 at 16:35):
If you choose to allow each profile to have it's own version - you'll enter version hell. If you choose to have all profiles upgrade the version with rest the group, you create false incompatibility. So: it's every which way but loose.
Michel Rutten (Sep 30 2018 at 16:36):
@Simone Heckmann mainly because it is "contageous" (like async)
Simone Heckmann (Sep 30 2018 at 17:52):
Anyone interested in having a session about this (Maybe in FHIR-I) ?
@Lloyd McKenzie ?
Ewout Kramer (Sep 30 2018 at 18:39):
Pre-processing all canonicals has one more big drawback: you cannot let the consumer of the package override version resolution anymore. Now, this is advanced, but if you include two packages, let's say A and B, and these two reference a different version of C, you need to be able to override either A and Bs dependency resolution at the moment of consumption of A and B. If you have turned all canonicals into hard-versioned ones, that is not possible anymore.
Simone Heckmann (Sep 30 2018 at 19:00):
I understand ( to some degree) however Stefan's concern, that if two people who download the same derived profile and implement it, they may end up with completely different (potentially incompatible) implementations, depending on how they resolved the dependencies.
We're assuming here, that everyone will use packaging and get packaging right. But that's probably not how it's going to be anytime soon...
Michel Rutten (Sep 30 2018 at 19:28):
Packages address so many challenges that I think this will soon become crucial and infrastructure for FHIR. Same as IDEs.
Michel Rutten (Sep 30 2018 at 19:32):
We will tightly integrate packages into our Firely tools (Forge, Simplifier, Vonk, Torinox). Our goal is to make the UI/UX as easy and simple as possible. I hope this will help drive adoption.
Lloyd McKenzie (Sep 30 2018 at 20:22):
My take is that if IG 1 depends on IG2 version A, then any profile that IG 1 that references another profile defined in IG 1, it's referring to the profile that's the same version it is. If it's pointing to a profile defined in IG 2, it's referring to the version A version of the profile. As such, you don't need to make the references version-specific.
Lloyd McKenzie (Sep 30 2018 at 20:22):
We'll see where we're at with scheduling items for this meeting. We might be able to afford another session on versioning.
Eric Haas (Oct 01 2018 at 14:42):
Thanks
Jens Villadsen (Oct 01 2018 at 22:42):
Why would we want to discourage it?
(Which brings us back to the question we started with): What are the pros/cons of explicit references?
Pro: you know exactly what you conform to - (on a side note, if you stick to semver, your representation of a resource may be syntactically compliant against a SD eventough the semantics have changed)
Pro: there is never any 'implicit' magic
Con: sounds like on @Stefan Lang that you are about to embrace nondeterminism
Con: being explicit can be cumbersome to maintain manually
If SD's can/should be treated as interfaces as in eg. Java, C#, Go, typescript ... whatever - then I wouldn't expect any other or better solutions to this matter other than what can already be found in regards to how interfaces are handled in those languages. 'Just' pick the poison you like the best
If I was a world dictator I would favour explicitness due to the fact that SD's describes the interface of a system - and I prefer to have that very clearcut carved in stone and welded in steel
Last updated: Apr 12 2022 at 19:14 UTC
