Stream: implementers
Topic: Canonical URLs
Alexander Henket (Jun 23 2016 at 11:22):
Hi. We're starting a bigger project and will be defining profiles in bulk. For this we need some conventions. Our current strategy is:
http://[domain]/fhir/[ConformanceResource]/[project]-[name]
example:
http://nictiz.nl/fhir/StructureDefinition/bgz-AllergyIntolerance
This seems to be comparable to what other projects are doing. What we are missing is a strategy for versions of profiles. I'm not talking about versions that you create as you develop but version 1.0 and 2.0. Is there any best practice?
Options:
http://[domain]/fhir/[ConformanceResource]/[version]/[project]-[name]
http://[domain]/fhir/[ConformanceResource]/[project]-[name]-[version]
...
Grahame Grieve (Jun 23 2016 at 11:25):
my advice on this is:
- when you make a breaking change, that's a new resource identity (new canonical URL) - this is semver mahor version. So you could write that into your URL at the start (or default -1 out, or something)
- the minor version is .version in the resource. you roll that over under manual control (or under some algorithm that tells the user/system when the minor version changes. e.g. for value set, any change to the content logical definition (per VSD spec) means a new minor version
Alexander Henket (Jun 23 2016 at 11:29):
Hi Grahame, thanks. I'm not worried so much about the decision to create a new profile (version) as opposed to updating the current version. I'm merely wondering about 'when I've determined I need a new canonical URL because I am creating a new profile version, where does the version part go in the canonical URL?' I'm sure I've got total freedom to create whatever URL I want, but if there's any lore on how to do this, I'd like to use it
Grahame Grieve (Jun 23 2016 at 11:35):
well, its usually appended as -X or just X
Grahame Grieve (Jun 23 2016 at 11:36):
but I've only seen a mahor version change actually happen once so far (usually, a major version change means a scope change and a new name anyway))
Alexander Henket (Jun 23 2016 at 11:39):
FHIR is young. It is only a matter of time before profiles start versioning more often I'm sure. Thanks for your answer. I guess that means we'll go with:
http://[domain]/fhir/[ConformanceResource]/[project]-[name]-[version]
Grahame Grieve (Jun 23 2016 at 12:22):
sure it will happen. it's just that we don't have much experience with ityet
Simone Heckmann (Jun 23 2016 at 13:38):
@Alexander Henket Just out of curiosity: What is http://[domain]/fhir going to resolve to? Are the profiles hosted at this endpoint (are you going to redirect to the project endpoint on simplifier) ?
Alexander Henket (Jun 23 2016 at 14:14):
Good question. We do not know yet. We come from V3 with 2386 templates, 1236 of which are active. Suppose that translates to roughly the same amount of profiles over time [we suspect a lot less, but for arguments sake], then we would need to maintain the same number of endpoints. That doesn't sound like a sustainable situation.
So... my current thinking is that we redirect all endpoints under http://[domain]/fhir to some kind of portal place [maybe just Simplifier] where you may find what you want rather than trying to make every single canonical URL resolve directly.
If bright ideas float around I'd love to be inspired by them.
Grahame Grieve (Jun 23 2016 at 21:16):
canonical URLs are really just registry references in the end
Simone Heckmann (Jun 24 2016 at 10:46):
Yes, but still: wouldn't it be nice if all these URLs resolved - at least - to a default site with a simplifier search box ;-)
Simone Heckmann (Jun 24 2016 at 10:49):
...or, for the sake of convenience: a prepopulated search box...
Simone Heckmann (Jun 24 2016 at 10:54):
BTW: Intuitively I'd expect http://[domain]/fhir to be a FHIR endpoint, no?
Simone Heckmann (Jun 24 2016 at 10:56):
Shouldn't we somehow distinguish the URL conventions for fhir namespaces and fhir endpoints?
Grahame Grieve (Jun 24 2016 at 10:57):
no, in many cases they are the same thing. The specification itself, for instance, and any IG published using the new IG infrastructure
Vadim Peretokin (Apr 05 2017 at 13:42):
Can you have dashes in [project] and [name]? @Alexander Henket the wiki doesn't disallow them explicitly
Grahame Grieve (Apr 06 2017 at 00:58):
yes
Vadim Peretokin (Apr 06 2017 at 06:43):
Awesome thanks
Ardon Toonstra (Apr 06 2020 at 13:57):
We are investigating the use of a semver major version number in the canonical URLs. (Similiar question asked by Alexander in the beginning of this thread in 2016). The R4 and build spec advice to do so: http://build.fhir.org/resource.html#versions
I am wondering if that advice is still present if you would take the fhir npm packages into account. We are currently versioning the conformance resources through packages.
Why should or shouldn't we include a major version number in the canonicals?
tom (Sep 14 2020 at 01:38):
Hi there! We're looking to provide our Questionnaires in FHIR for several of our health providers but need some advice around the canonical URL references between a QuestionnaireResponse and its corresponding Questionnaire
If our healthcare providers modify a Questionnaire, we'd like to increment Questionnaire.version and have all future QuestionnaireResponses reference this new version (QuestionnaireResponse.questionnaire) as the latest version reflects the set of questions that a patient would have answered
We can see that QuestionnaireResponse.questionnaire is a canonical reference that corresponds to Questionnaire.url
So if we have a new version of a Questionnaire (version = 2), would QuestionnaireResponse.questionnaire and Questionnaire.url be set to Questionnaire/my-questionnaire|2?
How would searching work? Doing the above and using the search Questionnaire/my-questionnaire|2 gives us a 404 on the https://vonk.fire.ly/R4 server so we're not sure we completely understand how this Questionnaire version and searching is intended to work
Grahame Grieve (Sep 14 2020 at 02:41):
I think your interpretation is correct. @Christiaan Knaap can you comment about the vonk server
Christiaan Knaap (Sep 14 2020 at 11:27):
Hello @tom ,
I have briefly tried. I only see version 10 on the R4 endpoint currently (twice even), and I can find them by searching for:
GET http://vonk.fire.ly/R4/Questionnaire?Questionnaire/594b8ddd-10d4-4357-b675-d0d685cd0772|10
Note that canonical url's are generally meant to be full urls.
There could be subtle issues here when referencing the Questionnaire by versioned url though, so please check back if you get unexpected results.
Maria Hu (Sep 14 2020 at 22:12):
I do not have the answer but I have similar issues.
-
Sample message provided on https://www.hl7.org/fhir/questionnaireresponse-example-gcs.json.html failed the validation when using "questionnaire": "Questionnaire/gcs"
"severity" : "error",
"code" : "structure",
"details" : {
"text" : "Canonical URLs must be absolute URLs if they are not fragment references (Questionnaire/gcs) "
},
"expression" : ["QuestionnaireResponse.questionnaire"] -
What is a proper format of using canonical URL for referencing Questionnaire in resource QuestionnaireResponse? Can someone send any example that is FHIR conformant? Thanks.
tom (Sep 15 2020 at 01:44):
Thanks @Grahame Grieve and @Christiaan Knaap , really appreciate your feedback
@Christiaan Knaap Using your search I'm getting a 400 Bad Request - Argument 'Questionnaire/594b8ddd-10d4-4357-b675-d0d685cd0772|10' lacks the name/value separator '=' or has no value
Adding url= in returns a bundle containing the Questionnaires, is this what you were using?
http://vonk.fire.ly/R4/Questionnaire?url=Questionnaire/594b8ddd-10d4-4357-b675-d0d685cd0772|10
I was hoping that by setting QuestionnaireResponse.questionnaire directly to the canoncial URL Questionnaire/594b8ddd-10d4-4357-b675-d0d685cd0772|10, this would resolve directly to the correct questionnaire too somehow - rather than needing to form the separate search term above (which also returns a bundle rather than just the Questionnaire). Is this not possible? Or is the canonical URL not supposed to resolve to the location of the resource on the server?
Interesting point about the full URL too.. In our case, all resources are located on our FHIR server so we been favouring relative URLs up until now to protect us if say we decided to ever move our data to a different server then these wouldn't need updating
Christiaan Knaap (Sep 16 2020 at 07:34):
Sorry @tom , for the copy/paste error, you inferred the correct query indeed (with url= in front).
What do you exactly mean by 'would resolve directly'?
- getting it with an include like this:
{base}/R4/QuestionnaireResponse?_include:QuestionnaireResponse.questionnaire - or using it in chained searches like this
{base}/R4/QuestionnaireResponse?questionnaire.url=Questionnaire/594b8ddd-10d4-4357-b675-d0d685cd0772|10
tom (Sep 16 2020 at 07:36):
(deleted)
tom (Sep 17 2020 at 01:27):
No worries @Christiaan Knaap ! Looks like I missed the url= when reading the docs too :smile:
So just to confirm that Questionnaire.url and QuestionnaireResponse.questionnaire should be set to the same thing - {base}/Questionnaire/594b8ddd-10d4-4357-b675-d0d685cd0772|10?
On the resolve directly part, I got mixed up between general and canonical references where general references are literal but we need to search for a canoncial reference using url=.
I've created another example of my-questionnaire where there is a version 1 and a version 2. It seems that the server returns both versions even if I explicitly search for version 1: url=https://vonk.fire.ly/R4/Questionnaire?url=https://vonk.fire.ly/R4/Questionnaire/my-questionnaire|1
Does this server not support searches using the |{version} notation? url=https://vonk.fire.ly/R4/Questionnaire?url=https://vonk.fire.ly/R4/Questionnaire/my-questionnaire&version=1 seems to work however
Christiaan Knaap (Sep 23 2020 at 07:12):
@Mirjam Baltus could you look into this in detail?
Last updated: Apr 12 2022 at 19:14 UTC
