Stream: implementers
Topic: URLs and FHIR Versions
Gino Canessa (Mar 03 2020 at 17:14):
Hi all, was working through parsing in different FHIR versions and had a question about URL resolution. Specifically, since canonical URLs aren't versioned, how are people resolving them? I did not see any hints on the Versioning Guidance page.
So far, I have questions around two cases:
1) Extension URLs, for example 1179-objectclass. The URL points to a StructureDefinition in the current (R4) version: https://www.hl7.org/fhir/extension-11179-objectclass.html , but if you want the DSTU2 version, you need to request https://www.hl7.org/fhir/DSTU2/extension-11179-objectclass.html .
- Is the general process that you should always inject the version into the URL? A DSTU2 server would have worked as expected when DSTU2 was 'current', but would have stopped working when STU3 was published.
- I chose that particular example because it exists in many versions, and the definition is different between them - trying to parse the wrong version will either fail or cause some unexpected behaviors.
2) Resource definition URLs, for example Appointment. Looking at a conformance statement from a DSTU2 server, the URLs are styled http://hl7.org/fhir/profiles/Appointment - which no longer resolve. The current style is http://hl7.org/fhir/StructureDefinition/Appointment. So again, if you need the DSTU2 version the URL you want is: http://hl7.org/fhir/DSTU2/StructureDefinition/Appointment .
- Are people just parsing and rebuilding those URLs to get the version they want?
- If so, does this mean that at some point everyone resolving DSTU2 URLs needed to change their code?
Any thoughts / experiences / advice is welcome, thanks!
Paul Lynch (Mar 03 2020 at 18:15):
As a side-note, the Versioning Guidance you linked to says to use version numbers rather than release strings, e.g. '1.0' and not 'DSTU2'. So your URL example for Appointment would look like http://hl7.org/fhir/1.0/StructureDefinition/Appointment. The LHC-Forms Questionnaire widget uses that format in meta.profile when generating Questionnaires.
Josh Mandel (Mar 03 2020 at 18:16):
I was thinking that maybe the "right" way to resolve these URLs is by downloading FHIR core conformance packages or looking things up in a registry. The conformance packages work okay for HL7-published content, but not so much for "open world" extensions. There, regsitries are the only approach I'm familiar with. But when I browse https://simplifier.net/ui/search/index?canonical=http://hl7.org/fhir/structuredefinition/11179-permitted-value-conceptmap I see dozens of copies of this extensions, all in different projects several of which look offical. Some match the published content, and some note exactly (for fields like status for example).
Michele Mottini (Mar 03 2020 at 18:25):
Why / when would you want to resolve those as part of parsing? (and: other servers might have extension URL that do not resolve ... for example ours...)
Gino Canessa (Mar 03 2020 at 18:27):
Thanks @Paul Lynch . Interesting that the HL7 server doesn't respect that guidance.
Gino Canessa (Mar 03 2020 at 18:37):
@Michele Mottini , I am working on some code generation software for OpenAPI. One of the options for configuration starts from a CapabilityStatement.
For some items, the Josh process works (e.g., I have FHIR 4.0.2 downloaded and can look up the model for an AllergyIntolerance). For 'official' extensions, this also works. The system breaks down when there are external definition for anything, since I don't have a version reference to work from. I figured it was easier to use the core specs as examples since they exhibit the same behavior.
I think a lot of my confusion is trying to addressed versioned resources without versioned URLs, and I am looking for how it is being handled 'in the wild'.
Paul Lynch (Mar 03 2020 at 18:57):
In LHC-Forms, if someone does not provide a versioned URL in meta.profile, we try to guess the version based on the structure of the Questionnaire. However, that guessing is not very good, and I think having a versioned URL in meta.profile should be considered necessary if you are going to send a resource to someone without the context of a FHIR server (which can tell you what version it is).
Josh Mandel (Mar 03 2020 at 19:02):
So that latter point is about how to tell what profiles are relevant for a given resource; but the @Gino Canessa questions are mainly about how to algorithmically resolve a definition URL (extension or profile) when the URL is known.
Grahame Grieve (Mar 03 2020 at 22:36):
the canonical URL is not necessarily a literal URL reference. Josh is right that you should get the right package and resolve through that.
Grahame Grieve (Mar 03 2020 at 22:37):
further, we have policy changes that mean that r2 is more broken than just in the versioning thing.
Grahame Grieve (Mar 03 2020 at 22:38):
there are redirects for versions - .e.g http://hl7.org/fhir/3.0/StructureDefinition/Appointment should work, and the package hl7.fhir.xver.r4 includes structure definitions that have version specific URLs, though only the canonical itsellf
Gino Canessa (Mar 04 2020 at 16:17):
Thanks @Grahame Grieve and @Paul Lynch. To make sure I have this right:
- for official definitions: download the correct versioned package and find the definition by matching URL
- for external definitions:
- hope the
CapabilityStatementhas a versioned URL that resolves to a definition - hope for a versioned URL in a resource
meta.profile - hope the server has a definition available for whatever you are looking for (e.g., a
StructureDefinitionfor an Extension)
- hope the
Josh Mandel (Mar 04 2020 at 16:52):
(And, to add to the "external definitions" bullet list:
- Gather versioned sets of all the definitions you can find for "common" stuff like US Core, possibly leaning on registries to help, and resolve URLs based on those when possible
)
Grahame Grieve (Mar 04 2020 at 19:38):
and the place to start is packages.fhir.org
Gino Canessa (Mar 04 2020 at 20:13):
@Grahame Grieve , I have been using http://hl7.org/fhir/<releaseName>/<packageName>.tgz (e.g., http://hl7.org/fhir/R4/hl7.fhir.r4.core.tgz) so far since the URLs are generic per release of FHIR.
In trying to get the downloads from the packages site, I wasn't able to find a URL that worked without the full version (e.g., 4.0.2). Is there one I didn't discover?
Grahame Grieve (Mar 04 2020 at 20:16):
well, if you want to avoid knowing the full version in advance, you have to search for the versions available: http://packages.fhir.org/hl7.fhir.r4.core
Gino Canessa (Mar 04 2020 at 20:19):
That's frustrating. Will those other URLs continue to work, or will they disappear at some point?
Gino Canessa (Mar 04 2020 at 20:21):
For reference, I am using the definitions at runtime. I don't want a dependency on NPM, nor do I particularly want to package all of the versions of FHIR at build-time.
Grahame Grieve (Mar 04 2020 at 20:23):
The others will continue to work. It's probably easier and more reliable to hit the main website for the core packages if you only want the current ones
Gino Canessa (Mar 04 2020 at 20:24):
Nice! Thanks!
Last updated: Apr 12 2022 at 19:14 UTC
