Stream: bulk data
Topic: Canonical URI for the Bulk Data CapabilityStatement
Lee Surprenant (Apr 01 2020 at 20:15):
At https://hl7.org/fhir/uv/bulkdata/operations/index.html it says:
To declare conformance with this IG, a server should include the following URL in its own CapabilityStatement.instantiates: http://www.hl7.org/fhir/bulk-data/CapabilityStatement-bulk-data.html
Lee Surprenant (Apr 01 2020 at 20:16):
Per the core spec, the value of that field should be a canonical uri for the CapabilityStatement. It seems weird to me that it ends in .html and even weirder given that this URL is not dereferencable
Lee Surprenant (Apr 01 2020 at 20:17):
maybe it should be https://hl7.org/fhir/uv/bulkdata|1.0.0 ?
Grahame Grieve (Apr 01 2020 at 20:19):
agree it should not include .html
Lee Surprenant (Apr 02 2020 at 13:41):
@Dan Gottlieb agree this one is worthy of a jira issue? ^
Dan Gottlieb (Apr 02 2020 at 13:57):
Definitely - do you mind opening one?
Josh Mandel (Apr 02 2020 at 13:58):
This feels extremely familiar. Either we had the same bug on another page, or we failed to fix it.
Dan Gottlieb (Apr 02 2020 at 13:58):
@Grahame Grieve is there a standard approach for incorporating the IG version in the capability url? I looked at a few IGs and most don't include the version, but US Core uses a dash followed by the version number: http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core-3.1.0
Dan Gottlieb (Apr 02 2020 at 13:59):
@Josh Mandel I think this was fixed in the capability statement JSON, but not the html page :rolling_eyes:
Lee Surprenant (Apr 02 2020 at 14:18):
Ah, I didn't even realize there was a CapabilityStatement shipped with the bulk data IG...how do I get to that?
Lee Surprenant (Apr 02 2020 at 14:24):
Opened FHIR#26683.
US Core uses a dash followed by the version number: http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core-3.1.0
IMHO including the version in the uri portion of the canonical is bad practice...canonical has a built-in way to support versioned references and it involves appending the version after a |
Lee Surprenant (Apr 02 2020 at 14:26):
And yeah, just double-checked, http://hl7.org/fhir/us/core/STU3.1/ImplementationGuide-hl7.fhir.us.core.html doesn't include the version after a dash. Do you know where you saw that?
Lee Surprenant (Apr 02 2020 at 14:28):
http://hl7.org/fhir/us/core/STU3.1/CapabilityStatement-us-core-server.xml.html agrees:
<url value="http://hl7.org/fhir/us/core/CapabilityStatement/us-core-server"/> <version value="3.1.0"/>
Dan Gottlieb (Apr 02 2020 at 14:35):
Interesting! The dashed version is used where the US Core server CapabilityStatement references the the US Core IG in http://hl7.org/fhir/us/core/STU3.1/CapabilityStatement-us-core-server.json.html
"implementationGuide" : [
"http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core-3.1.0"
],
Lee Surprenant (Apr 02 2020 at 14:46):
smells like another bug...care to open that one against US Core or should i have a go?
Dan Gottlieb (Apr 02 2020 at 15:00):
I can follow up on US Core, but just taking out the version isn't a great solution. Fundamentally it seems like version numbers should be baked into the IG canonical urls (preferably in a de-referenceable manner) so that CapabilityStatements are declaring support for a particular IG version (eg. https://hl7.org/fhir/uv/bulkdata/1.0.0).
Lee Surprenant (Apr 02 2020 at 15:03):
thats why i say it should follow the canonical pattern: uri|version
Lee Surprenant (Apr 02 2020 at 15:03):
https://hl7.org/fhir/uv/bulkdata|1.0.0
Lee Surprenant (Apr 02 2020 at 15:03):
http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core|3.1.0
Lee Surprenant (Apr 02 2020 at 15:04):
the uri part of it should be dereferencable
Lee Surprenant (Apr 02 2020 at 15:04):
but will take you to the "latest"
Dan Gottlieb (Apr 02 2020 at 15:09):
Why not include the version in the URL though, so it takes you to the actual version that was implemented?
Josh Mandel (Apr 02 2020 at 15:11):
Ideally all the things that we write down would resolve. Version references would be referencable and resolve to the right version. It's not hard to describe "good" behavior... but I don't know that we have control over the HL7 web server in a way that permits all this to happen correctly. I know Grahame has done quite a bit on this front, but also hit limitations.
Lee Surprenant (Apr 02 2020 at 15:18):
Why not include the version in the URL though, so it takes you to the actual version that was implemented?
because its a canonical reference and the community had decided that those should follow the pattern i mentioned above: https://www.hl7.org/fhir/references.html#canonical
I know Grahame has done quite a bit on this front, but also hit limitations.
Yeah, I'm guessing its not possible, but it would be cool if a canonical uri could dereference to the version being referenced; i.e. https://hl7.org/fhir/uv/bulkdata|1.0.0 -> https://hl7.org/fhir/uv/bulkdata/1.0.0 -> http://hl7.org/fhir/uv/bulkdata/STU1
Josh Mandel (Apr 02 2020 at 15:21):
I think Dan wasn't saying "why not include the version as a path component" -- I took him to be saying "let's make sure not to propagate versionless references"
Josh Mandel (Apr 02 2020 at 15:21):
Including a version with a pipe delimiter avoids propagating versionless references.
Josh Mandel (Apr 02 2020 at 15:23):
(Gosh I'm feeling bad about these double negatives, but it's hard to write precisely here.)
Basically I think Dan was saying that for purposes of conveying enough information:
- Bad: "https://hl7.org/fhir/uv/bulkdata"
- OK: "https://hl7.org/fhir/uv/bulkdata|1.0.0"
- OK: "https://hl7.org/fhir/uv/bulkdata/1.0.0"
... am I reading you right @Dan Gottlieb ?
Dan Gottlieb (Apr 02 2020 at 15:26):
Yep, exactly (sorry, I expressed the idea poorly)! I don't have a preference between the latter two of Josh's examples, though if one could be made de-referenceable on the HL7 server, that would get my vote for a best practice :)
Lee Surprenant (Apr 02 2020 at 17:17):
ok, makes sense. and i think my opinion was already clear, but i'll say again anyway; i think fhir core says https://hl7.org/fhir/uv/bulkdata|1.0.0 is "correct" and https://hl7.org/fhir/uv/bulkdata/1.0.0 is not (unless you make that the value of the CapabilityStatement.url field as well, which does not seem right to me)
Dan Gottlieb (Apr 02 2020 at 17:54):
Yeah, I agree that that the pipe delimited version fits with the FHIR url rules. In the next update, I'll go through and try to align everything between the html docs, the canonical ig url, and the capability statement url and references.
Grahame Grieve (Apr 02 2020 at 19:52):
I think I can make |version work on hl7.org, but I'd have to check
Grahame Grieve (Apr 02 2020 at 19:52):
I'm not sure what's the deal with the US core approach
Brett Marquard (Apr 02 2020 at 23:51):
I don't remember the conversation on why we picked what we did in US Core - Do you @Eric Haas ?
Brett Marquard (Apr 02 2020 at 23:51):
@Lee Surprenant suggestion for bulk seems logical for US Core also. If you would be willing a tracker would be great.
Eric Haas (Apr 03 2020 at 00:19):
(deleted)
Eric Haas (Apr 03 2020 at 00:19):
(deleted)
Eric Haas (Apr 03 2020 at 00:46):
When we were publishing the IG "http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core|3.1.0" generated a qa error because the package file listed it as "http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core-3.1.0"
We went with what worked at the time.
Lee Surprenant (Apr 03 2020 at 13:39):
@Brett Marquard FHIR#26686
Yunwei Wang (Apr 06 2020 at 14:15):
Josh Mandel said:
This feels extremely familiar. Either we had the same bug on another page, or we failed to fix it.
I raised this and some other CapabilityStatement issues during last September's connectathon. Here is the tracker item created: FHIR#24434
Josh Mandel (Apr 06 2020 at 15:49):
So... this was part of what we decided to fix in our "technical correction," and we updated the github repo (master branch) but never managed to publish the technical correction to http://hl7.org/fhir/uv/bulkdata. @Grahame Grieve or @Lloyd McKenzie, can you help us understand the steps involved in publishing these corrections that FHIR-I decided to address?
Lloyd McKenzie (Apr 06 2020 at 16:20):
Once made, we'll have to do a review of the updated spec to make sure it contains what it's supposed to (and only what it's supposed to), then submit a "publication request" to the TSC. Template is here: https://confluence.hl7.org/display/HDH/How+to+Create+a+Publication+Request+from+Template
Last updated: Apr 12 2022 at 19:14 UTC
