Stream: implementers
Topic: fhirVersion representation in CapabilityStatement
Kevin Olbrich (Mar 11 2017 at 16:59):
According to 1.9.0, the fhirVersion listed in the CapabilityStatement is an 'id'. It seems to me that a better choice might be to publish a ValueSet of fhir versions and then represent that value as a CodeableConcept. The advantage of this is that the value set could include a human readable text representation of the version (i.e.,{ 'code': '1.8.0', 'text': 'This is the FHIR STU 3 Candidate, and the version for the San Antonio Connectathon in Jan 2017.'}). It would also be possible to publish multiple value sets and setup concept maps to translate back and forth between the semantic version and the '2017Jan'-style versions. Thoughts?
Lloyd McKenzie (Mar 11 2017 at 21:05):
It might cause problems with future compatibility
Mario Hyland (Mar 12 2017 at 23:49):
This might be worth further discussion during the next WGM in Madrid Spain - my initial thoughts are along the same lines as @Kevin Olbrich - as we watch organizations publish and test their FHIR Capability Statements - as an xs:string ID value; if you think about the FHIRversion and a potential use case where a FHIR Client might want to interegate a FHIR Server (End-Point) in order to validate indeed which version of FHIR do you currently support. Would seem some authorized published list (aka ValueSet) codeified value for each published version of FHIR would be valueable to the FHIR community. I know we currently test for it. The values we expect to see are 1.0.2 (for DSTU 2), 1.4.0 (for STU 3 - for Connectaton 12 Montreal), 1.6.0 (for STU 3 - for Connectathon 13 Baltimore, 1.8.0 (for STU 3 - for Connectathon 14 San Antonio). We would assume 2.0.x (for STU 3 Official) for the next Connectathon 15 - Madrid Spain.
Kevin Olbrich (Mar 13 2017 at 13:03):
I would even go so far as to suggest that there should be one and only one way to refer to the version of fhir (both in written documentation and in URLs and published artifacts), and it should be the semantic number. We should bump the semantic number to match the STU number (so the official published release of STU3 would be 3.0.0), and then we should stop using the STU/DSTU convention, I think it just confuses people.
Mario Hyland (Mar 13 2017 at 13:06):
Agreed, FHIR V1.0 (DSTU 2) and FHIR V2.0 (STU 3) has confused many folks, I hear myself explaining this a number of times. So, I could see DSTU 2 and FHIR V2.0 being confused as the same version.
John Moehrke (Mar 13 2017 at 13:23):
Seems to me "FHIR v2" would be confused by many as meaning the Second Normative release. The confusion between build number and STU release number is only confusing to a few. The first number in the version should have been kept zero (0) until something went normative. Yet missunderstanding between STU and Normative would cause major problems. The broader audience must continue to understand the status as STU (DSTU); it is not normative yet.
Mario Hyland (Mar 13 2017 at 14:11):
Ok, good points John - reviewing the FHIR Version page (https://www.hl7.org/fhir/directory.html) - what would you suggest. It is almost certain that a number of flavors of FHIR projects will go into the pilot stage between now and when an official Normative version of FHIR is published. Those efforts will have FHIR Client and FHIR Servers which need/should broadcast a FHIRverion number of some type. Ideas?
John Moehrke (Mar 13 2017 at 15:05):
That is a technical version... so I don't see any conflict with using the numeric version number as given on that directory page. Computers don't get confused by "2.0.0" == "STU3". It is simple string substitution. It is only dang inference engines called Humans that have the problem, and it is that inference engine that most of the time infers wrong.
Grahame Grieve (Mar 13 2017 at 20:37):
there will not be a 'Normative' release. we deliberately chose to move to 1.0 for the DSTU2 release when it was clear that there wouldn't be a single fully normative release
Grahame Grieve (Mar 13 2017 at 20:38):
I've wondered wheher we should align the primary version number with the stated release, and just skip a version. we've got 5 days to decide to do that
Grahame Grieve (Mar 13 2017 at 20:38):
(seems unlikely)
Grahame Grieve (Mar 13 2017 at 20:39):
we can valueset the version field if we want.
Lloyd McKenzie (Mar 13 2017 at 20:52):
If we do valueset it, we'd need to make it extensible so people using past versions can accept future ones
Kevin Shekleton (Mar 14 2017 at 02:34):
@Grahame Grieve - FWIW, I think it would be great to align the version number with the release. Making this change with STU3/1.9 probably is not good at this point, but something that is discussed for the next release
Grahame Grieve (Mar 14 2017 at 02:37):
well, it's going to be 2.0
Grahame Grieve (Mar 14 2017 at 02:38):
there's no guarantee, under our currrent system, about odd//even, though it's working that way .
Grahame Grieve (Mar 14 2017 at 02:38):
but we could go to 2.1b for the current build, instead of just 2.1
Kevin Shekleton (Mar 14 2017 at 02:39):
Sorry, I just realized I had a crucial missing word -- I meant that making this change now would "not" be good given how close we are to the release
Grahame Grieve (Mar 14 2017 at 02:39):
it's possible, if we choose, to go to 3.0 instead of 2.0
Grahame Grieve (Mar 14 2017 at 02:39):
that's a purely arbitrary decision and we will hike the major version - in the nexst few days
Kevin Shekleton (Mar 14 2017 at 02:41):
I logged this for future discussion: http://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_item_id=13027
Kevin Mayfield (Mar 14 2017 at 08:51):
Using 3.0 seems straightforward.
Paul Knapp (Mar 14 2017 at 12:08):
+1
Mario Hyland (Mar 14 2017 at 15:02):
+1, I think this would be a great idea (given DSTU 2) - i think this "removes" a lot of potential industry confusion.
John Moehrke (Mar 14 2017 at 15:02):
Would have been best to have kept the first number at zero ( 0 ) until something went Normative... but missing that, then it seems aligning the first number with the STU number is logical... We do have an infinite number of numbers, so we will not run out.
Richard Ettema (Mar 14 2017 at 17:54):
+1, I agree setting the new version to 3.0 would help; especially when I hear references to the next release as "R4".
Jenni Syed (Mar 21 2017 at 19:26):
Late to the party: but as to the valueSet idea, I've heard some developers discuss adding their own local versioning. IE: this is version 3.0.0_MYTAG. Primarily discussed in the context of allowing developers to track bug fixes and enhancements to a specific implementation
Jenni Syed (Mar 21 2017 at 19:28):
if that was ever actually put into practice by a server, it feels like it should use a separate field anyway. Requiring a valueset here makes that more explicit... but something to consider if we went that way
Michael Lawley (Apr 05 2017 at 12:09):
Isn't that what the software version field is for?
Mario Hyland (Apr 29 2017 at 16:05):
@Lloyd McKenzie and @Josh Mandel inviting you to this thread - following up on my presentation at #FHIRNorth and our discussions as it relates to fhirVersion being a ValueSet / Codified / predefined values. RIght now fhriVersion element is ID (Any combination of upper or lower case ASCII letters ) - http://www.hl7.org/fhir/datatypes.html#id
Josh Mandel (Apr 29 2017 at 22:11):
Yes -- let's bring this up in a FHIR-I call. I think binding to an extensible predefined list would be good.
Lloyd McKenzie (Apr 29 2017 at 23:16):
Agree. Any objections @Grahame Grieve?
Grahame Grieve (May 01 2017 at 05:21):
what's the list? I don't think it's that easy
Lloyd McKenzie (May 01 2017 at 16:34):
I think just codes for the official releases should be in the primary value set, though we could create an additional value set with codes for each of the ballot/connectathon releases
Grahame Grieve (May 01 2017 at 21:04):
what's the purpose of allowing you to state anything other than the current valid version?
Abbie Watson (May 01 2017 at 23:00):
Supporting legacy apps that don't have unlimited funding to hire a team of developers to keep up to date with the latest release. Supporting small startups with limited budgets, not just large players. Supporting not-for-profits with limited budgets.
Heck, even open.epic.com is still on DTSU2. It's not like even the big players are keeping up to date on the current valid version.
Josh Mandel (May 01 2017 at 23:02):
+1 to that @Abigail Watson
Grahame Grieve (May 02 2017 at 01:00):
that missed the point. Why would you use a R3 capability statement with any value other than "3.0.1"?
Grahame Grieve (May 02 2017 at 01:00):
I can't see why you'd use a R2 capability statement with anything but "1.0.2"
Abbie Watson (May 02 2017 at 03:56):
:facepalm: Uh, because real life happens? Because we just spent 6 months implement to v1.6.0; and that's just where we onramped onto the process?
Grahame Grieve (May 02 2017 at 03:59):
so you're using a v1.6 conformance statement?
Abbie Watson (May 02 2017 at 04:01):
We were; then we spent weeks upgrading to v3.0.0, but haven't made it to v3.0.1 yet. We do quarterly releases, so it will probably be another 2 months yet before we can even think about v3.0.1.
Abbie Watson (May 02 2017 at 04:05):
And it was a push to get from v1.6.0 to v.3.0.0. I had to drop another project to get it out the door. From an implementors perspective, we've got a bunch of real-world constraints that limit our ability to move forward to the latest version. Quality control checks, integration tests, release cycles, training of team members, etc. That all has to be coordinated. And just because I was able to upgrade the base build to v.3.0.0 doesn't mean that any of the implementations got upgraded. They're still sitting at v1.6.0 at a half-dozen places.
Lloyd McKenzie (May 02 2017 at 12:22):
v3.0.0 and v3.0.1 are identical from a conformance perspective. (If we had a version code it would be limited to 3.0 - or more likely STU3 or R3).
Grahame Grieve (May 02 2017 at 22:25):
still, I don't see a use case for mixing versions in capability statement. There is in StructureDefinition, and I routinely do that
Abbie Watson (May 03 2017 at 00:40):
I don't think Mario's suggestion is for an array of fhirVersions in the capability statement. The request isn't to have a cardinality of greater than 1. It's to have standardized codeset, so folks aren't coding it up as fhir-3.0.1 vs FHIR301 vs STU3 vs fhir_3_0_1 vs fhir-3-0-1, etc.
Grahame Grieve (May 03 2017 at 00:44):
I still haven't seen a use case for anything but a fixed value ('3.0.1')
Josh Mandel (May 03 2017 at 01:13):
Let's assume R4 comes out and still has a CapabilityStatement. Wouldn't you want to populate its version with something like "v4.0.0"? Shouldn't an app have a simple way to tell R3 from R4?
Lloyd McKenzie (May 03 2017 at 01:52):
Why would you do '3.0.1' instead of just '3.0'?
Pascal Pfiffner (May 03 2017 at 04:08):
@Lloyd McKenzie I'm pretty sure every parser would treat "3.0" and "3.0.0" as equal, but what I've seen, especially in Git tags, is increasing consistent use of the "Major.Minor.Patch" scheme (http://semver.org). Since we're cool we may also want that. ;)
Abbie Watson (May 03 2017 at 04:13):
So, ignoring the fhir- prefix, can we just agree on a codeset of the published versions? All the recent releases are following semver, and they're well defined. But lets be clear that it's 3.0.1 and not v3.0.1 or STU3 or '3_0_1`, etc. That's all that's being asked, I think.
http://hl7.org/fhir/directory.html
Grahame Grieve (May 03 2017 at 04:28):
it should definitely be 3.0.1, not anything else. maybe it should be a fixed value, but you could at least create a task to calrify
Mario Hyland (Jun 19 2017 at 20:17):
@Josh Mandel @Lloyd McKenzie and @Grahame Grieve do we know if this has advanced since our discussions from FHIR North? Do we need some one to create a GForge Ticket? I know we have a larger discussion around FHIR Version on going, but I think we can separate it for this thread. FHIRversion - change from ID type (freeform field) to some type of code/value set?
Grahame Grieve (Jun 19 2017 at 20:18):
I don't understand why we would change to a value set.
Grahame Grieve (Jun 19 2017 at 20:18):
there's only one valid value. We should fix the value
Mario Hyland (Jun 19 2017 at 20:21):
There are differing implementation out there, not everyone is using "one" value. We have DSTU 2.0.1 servers testing, we have STU 3 - version 1.8.0 servers testing, and now we have 3.0.1 servers. during the R4 efforts we will have folks testing 3.0.x (which ever version you publish next). As Abigail said earlier - we are seeing everything from v3.0.1 to STU3, etc.
Grahame Grieve (Jun 19 2017 at 20:22):
the value for a single version of the specification is a fixed string.
Grahame Grieve (Jun 19 2017 at 20:22):
e.g. 3.0.1
Richard Ettema (Jun 19 2017 at 20:53):
@Grahame Grieve Yes, the fhirVersion value for any specific version is a fixed string. The issue is "what are the allowed fixed string values?" DSTU2 official is "1.0.2". Each intermediate release leading up to STU3 is "1.1.0" (or "1.2.0" based on the actual version used for Connectathon 11), "1.4.0", "1.6.0" and "1.8.0". STU3 Official started with "3.0.0" and is now "3.0.1". So, I guess the question is "how do we know what the allowed fixed string values are?" I could specify that I support fhirVersion equal to "1.9.0" - is that legal/allowed as that was never a published version of the FHIR specification? The current CI build is "3.1.0". Can I use that? If so, that would seem problematic as the CI build is a moving target.
Richard Ettema (Jun 19 2017 at 20:54):
The FHIR Publication Directory page, http://hl7.org/fhir/directory.html, provides guidance but not specific instructions to implementers. The CapabilityStatement fhirVersion definition - "The version of the FHIR specification on which this capability statement is based" - also leaves it open for interpretation.
Richard Ettema (Jun 19 2017 at 21:04):
The FHIR Version History page, http://hl7.org/fhir/STU3/history.html, seems a likely place to find valid version (fixed string) values. The only caveat is that "1.5.0" and "1.9.0" are listed but do not represent actual released versions.
Grahame Grieve (Jun 19 2017 at 21:42):
1.5.0 represents a version that was 'released' but for HL7 does not maintain a published version. But there might be people out there with their own copy. It's not invalid for them to use it if they do. There's people out there with v0.4 in production
Grahame Grieve (Jun 19 2017 at 21:43):
I agree that it would be good for the CapabilityStatement version to be fixed in the specification.
Grahame Grieve (Jun 19 2017 at 21:43):
but we can't answer the question 'what are the allowed fixed string values'. There is only one allowed fixed string: the current version.
Mario Hyland (Jun 19 2017 at 21:46):
But a client presumably (server or client) could contact any number of servers - and may adapt to the version of FHIR. If a FHIR instance can process multi-version - it must have a way to evaluate "valid" versions. Agreed server publishing as a single version only has one version. But, we are supporting a wider ecosystem - where multiple FHIR implementations may exist simulatneous.
Jenni Syed (Jun 19 2017 at 21:47):
Wouldn't that client need to be able to handle all fhir versions it understands? IE: it already handles the fact that a specific field in the resource is there/not there/different name/different value set based on version. It doesn't need that value set to be the full representation of everything that's been valid throughout history
Jenni Syed (Jun 19 2017 at 21:48):
Same issue here: it knows that for the 5 FHIR versions it handles, each version only allows 1 specific value in that conformance statement.
Jenni Syed (Jun 19 2017 at 21:50):
Possibly the only reason to allow for more than one version would be for revision? Isn't that bumped for non-substantive/doc changes after release? Though that become chicken and egg if a doc change causes a value set change? :)
Mario Hyland (Jun 19 2017 at 21:54):
As an example - I would offer the following - attached are the FHIR implementations currently testing with Touchstone Touchstone-FHIR-Versions-in-the-wild.jpg - these servers/client can and do try to interact with various other test systems. An ability to query a FHIRversion - with predefined values would allow downstream conformance related processing.
Grahame Grieve (Jun 19 2017 at 22:08):
what does 'query a FHIRversion' mean?
Grahame Grieve (Jun 19 2017 at 22:09):
what that demonstrates is that we haven't specified a fixed version, and we should. And that people can't copy from examples :-(
Jeffrey Danford (Jun 19 2017 at 22:12):
Do we have two questions here? One about explicitly stating how to represent FHIR versions (e.g. 1.0.2 or 3.0.1 vs v102 or STU3) and another about how to represent a service that support resources for multiple FHIR versions?
Grahame Grieve (Jun 19 2017 at 22:15):
at the moment, there's no such thing as a 'service that supports multiple FHIR versions' - it would put up different end points. E.g. http://test.fhir.org/r2 and test.fhir.org/r2
Richard Ettema (Jun 20 2017 at 00:38):
Ok. After reviewing the FHIR specification on FHIR Releases and Versioning, http://build.fhir.org/versions.html#versions, I would have to say that the fhirVersion value needs to conform/follow this description - "Each FHIR version is identified by a string composed from 4 parts: publication.major.minor.revision." The actual format could be defined as follows:
Richard Ettema (Jun 20 2017 at 00:38):
publication.major.minor{.revision} - where if revision is ommitted, the most current (svn) revision number of the version represented by publication.major.minor is expected.
Richard Ettema (Jun 20 2017 at 00:38):
This would at a minimum deal with the formatting issues for the fhirVersion value.
Grahame Grieve (Jun 20 2017 at 05:36):
ok I take it back. It's not true that there's a single fixed version for fhirVersion in either CapabilityStatement or StructureDefinition. For operational systems, that should be true. really SHOULD be true for CapabilityStatement. But in the tooling space, there's a variety of reasons why both those fields might have old versions. I'm going to bind those two fields to a value set so we can see what it looks like
Mario Hyland (Sep 15 2019 at 16:37):
Hello everyone, I am revisiting this topic. We recently heard about a FHIR Server implementation which was going to support multiple versions of FHIR at a single end-point. The implementation was going to leverage FHIRVersion reference in the HTML Header Mime Type Parameter (which FHIR now supports). However, I do NOT see how the client would know if the server supports this mime type version reference. Seems to me the FHIR Capability Statement should now include a field which allows a FHIR Server to identify whether it supports Mime Type reference to version. I only say this because the references I have read regarding this HTML Header Mime-Type (URL Encoding) is not SHALL or Required at this time. If I were a client, and I ran into a server which broadcasted multiple version support - I would want to know if they support this Mime-Type feature https://www.hl7.org/fhir/versioning.html
Grahame Grieve (Sep 15 2019 at 17:37):
have you looked at the $versions operation?
Kevin Olbrich (Sep 16 2019 at 13:47):
@Mario Hyland another approach would be to request the CapabilityStatement using an Accept header containing a prioritized list of versions the client cares about. The server should return the CapabilityStatement of the first one that matches and you can then use that and the Content-Type header on the response to identify the best FHIR version to proceed with. As Grahame mentioned you can use the $versions operation to figure out the list if you really want to, but I don't think it's necessary in most cases.
Last updated: Apr 12 2022 at 19:14 UTC
