FHIR Nuts & Bolts: Versioning v2

Chris Grenz
EIM Practice Director at Analysts

WGM Sept, 2017 in San Diego and the FHIR versioning discussion continues. A previous post set the table on this discussion, and I still maintain my conclusions. However, additional comment by Grahame and the folks from Cerner (Jenni, Kevin) makes me want to add some color.

Read the first article if you've not gotten there. Remember that we're trying to solve 2 issues here:

- API Versioning: the operation of the endpoint, like query parameters, HTTP headers and status codes, etc.

- Content Versioning: in situations where an API context isn't available (messaging, file/object storage, etc.) or isn't limited to a single version (think aggregators, interface engines, etc.), determining the schema/semantics of the resource content.

A Normative World

If all goes to plan, the next version of FHIR will include normative sections, functionality that will remain stable according the forward/backward compatibility rules. The first normative will include a handful of the most stable resources and the ReST API itself.

In the wild then, we'll have a variety of servers implementing a wide mix of capabilities. As the standard matures, these capabilities may expand and servers may upgrade to support them or may simply continue to act as they have. What will not happen is that behavior will simply change in a version-specific way. In other words, the first of the two issues, API Versioning, generally ceases to be an issue in normative space since the API will only be expanded or refined in a non-breaking way. Yes, DSTU2 and STU3 APIs will continue to exist and something clever could be done to retroactively add support for API versioning back to these levels. But generally, I think capability discovery is going to dwarf API versioning as an issue and the breaking API changes between pre-normative API versions should continue to be supported via version specific base URLs.

The content side though is an entirely different situation. As I mentioned in the previous article, there will for many years be a mix of STU and normative content in the wild, and that content will not always be wrapped in a MIME-type capable wrapper. Messaging in fact specifically calls out the use of files as a valid transfer protocol, and bulk data applications will certainly use files extensively.

HTTP Content Negotiation

During the FHIR-I session on the topic there was quite a bit of traction for the idea of using HTTP content negotiation in the ReST interface, (and potentially in any other transport that could support it). This paradigm, using GitHub's API as the model, selects how the FHIR endpoint acts in terms of both the API version and the content version (in most scenarios).

This is elegant in its conformance to the ReST paradigm, but we've really only improved the ReST API interface which already worked pretty well with version specific URLs. I agree this is better, but we didn't solve the issue of dealing with messaging or other exchange paradigms where the wrapper can't carry the context. So let's do this, but it's not enough.

Embedded Version

Since the remaining use case assumes that version can't be reliably carried outside the resource, we're forced to consider how to represent version inside the resource. As I mentioned previously, we must avoid giving specific version numbers to normative resource content if we want to avoid interoperability penalties. STU content on the other hand must be versioned specifically since it breaks between versions.

I'll refer everyone back to the previous article for illustrations of various embedded versioning schemes, many of which rely on specific version numbers, (which I would oppose).

Profile Based Still Ahead

In a post-normative world, profile-based version continues to lead the pack of potential solutions for content versioning:

- STU resources have snapshot grain for versioning, (each FHIR snapshot, e.g. 2017Jan for the San Antonio WGM, would have a canonical profile URL). A technical correction could apply these retroactively for STU profiles. And, going forward, tooling would naturally apply the correct profile lineage for STU resources.

- Normative resources are, (as they must be), compatible with the current normative schema and no conformant system may "lock in" clients to specific FHIR versions for normative content, (no forced upgrades).

- Best retroactive application as meta.profile has been present since long, long ago.

- Existing tooling that uses the baseDefinition profile lineage would work out-of-the-box with this solution.

As always, I love to hear comments, either here or on chat.fhir.org with the entire implementer community.