FHIR Chat · Advice on terminology services · IG creation

Stream: IG creation

Topic: Advice on terminology services

view this post on Zulip Brett Esler (May 03 2018 at 10:38):

With some new terminology services holding specific IG related CodeSystems and ValueSets being available to me (non core)- if I wish to bind to a ValueSet directly held in a terminology server in profiles and build in IG builder will that make sense? I can certainly reference another IG containing the ValueSet and IG builder will resolve an link will navigate as expected. Can I reference valuesets directly? e.g https://healthterminologies.gov.au/fhir/ValueSet/australian-indigenous-status-1

view this post on Zulip Grahame Grieve (May 04 2018 at 02:12):

do you want to publish them as part of the IG and just source them directly? Or just reference them directly without any publishing for them?

view this post on Zulip Dion McMurtrie (May 04 2018 at 03:31):

I think you want to just reference them from the IG and then when you follow the link to them you get a rendering which describes the ValueSet and lets you look at the expansion (like the link you provided). The aim is for those ValueSet urls to provide the ability to reference specific versions of the ValueSet or "latest" where that makes more sense for the binding to track latest.
Or am I misunderstanding? (there's a good chance of that!)

view this post on Zulip Grahame Grieve (May 04 2018 at 03:42):

well, this is tricky. Is the TS link version specific?

view this post on Zulip Grahame Grieve (May 04 2018 at 03:43):

and what's the link for the browser ? not the same as the restful link?

view this post on Zulip Dion McMurtrie (May 04 2018 at 03:45):

the links can be version specific or a link that is the "latest" version, so it can be referenced either way. the response is based on the accept header - if you ask for HTML you get a rendering (try the link @Brett Esler put in) but if you put in FHIR JSON or XML accept header you get a FHIR REST response

view this post on Zulip Grahame Grieve (May 04 2018 at 03:45):

I think it needs to be a version specific reference, so that old versions of the IG say what they originally said

view this post on Zulip Dion McMurtrie (May 04 2018 at 03:46):

that particular link is tracking the 1.x major version of that ValueSet, so it will point to 1.1, or 1.2 or whatever is the latest...but we can reference 1.1 precisely...or just absolute latest

view this post on Zulip Dion McMurtrie (May 04 2018 at 03:49):

that's the idea, that IGs can express what is important, pin to a specific version, a major version (and tolerate minor updates) or just absolute latest, whatever makes sense in the context of that binding. The aim is that if the underlying VS changes in ways that aren't significant to the binding the IG can track the major version and not have to up rev each time something small happens...but it does require care be taken about what a "major" and "minor" changes are

view this post on Zulip Dion McMurtrie (May 04 2018 at 03:50):

probably intended that most common binding will be to major version

view this post on Zulip Brett Esler (May 04 2018 at 04:07):

Version specific makes sense; I would like to reference valuesets but not publish them (in some places); currently get the link appearing in the IG as url and resolves ok to the external HTML... so think this is correct as far as this discussion goes - so I should not assume the ValueSet definition is resolved and the display title like explicit ValueSets defined in the IG correct? e.g.

view this post on Zulip Brett Esler (May 04 2018 at 04:07):

pasted image

view this post on Zulip Brett Esler (May 04 2018 at 04:08):

@Dion McMurtrie what would the version specfic url be for NCTS valuesets?

view this post on Zulip John Grimes (May 04 2018 at 05:08):

@Brett Esler That binding URL should be the canonical version, https://healthterminologies.gov.au/fhir/ValueSet/anzsco-1.

view this post on Zulip Dion McMurtrie (May 04 2018 at 05:42):

OK @Brett Esler I've tracked this down and warmed up my memory...I was probably misleading...and like all of these things it is a bit complicated and there's trade-offs

This all had to do with a requirement of our CI team (IMO sensible) for stable references for bindings so that minor VS changes don't cause unnecessary IG version churn. But...there is only one “url” field in the resource which is really an identifier, and again I think sensibly, CI want the reference to be that value. We’ve chosen to make those resolvable (which is good).

To meet these criteria we chose to make the url major version specific, not minor version specific. So for example
https://healthterminologies.gov.au/fhir/ValueSet/australian-states-territories-1
https://healthterminologies.gov.au/fhir/ValueSet/australian-states-territories-2

Those the 2 urls are for versions 1.0.0 and 2.0.0 of the ValueSet. Had there been a 1.0.1 business version published it would have had the same "url" element value as the 1.0.0 version (the above url), and https://healthterminologies.gov.au/fhir/ValueSet/australian-states-territories-1 would return the 1.0.1 version once published.

That allows for the stability of the binding for the IG with the ability to modify the ValueSet in "minor" ways if needed. I’m not sure exactly what rules we’ve created for the minor and patch versions – @Liam Barnes is there any definition yet?

But for instance patch versions might be corrections to spelling errors in some of the resource’s fields, like the description. A minor version change might include addition of a new code (although this may depend on the ValueSet’s purpose, its definition, and underlying code systems - @Liam Barnes can you confirm the rules here).

Now we could (but currently don't) make available a URL that returns version 1.0.0 and another that returns 1.0.1, i.e.

https://api.healthterminologies.gov.au/integration/v2/fhir/ValueSet/australian-indigenous-status-1.0.0
https://api.healthterminologies.gov.au/integration/v2/fhir/ValueSet/australian-indigenous-status-1.0.1

But those wouldn’t be the value of the “url” element of the resource (really an identifier) which is https://healthterminologies.gov.au/fhir/ValueSet/australian-states-territories-1 both 1.0.0 and 1.0.1 would have this as their “url” field value. Basically that "url" identifier can only have one value, hence the need for a decision and trade off.

If IGs want to bind to the specific version (i.e. 1.0.1 rather than 1.x.x) and they need to do that by referencing the “url” element value of the ValueSet resource, then we’d have to change what we’ve done. But it is a trade off, because then you’ve got no way to reference 1.x.x using it's "url" element value which was the original requirement to avoid unnecessary churn in IG versions.

We could (but currently don't) also make a URL that resolves to the latest version of the ValueSet

https://api.healthterminologies.gov.au/integration/v2/fhir/ValueSet/australian-indigenous-status
or maybe better to be explicit
https://api.healthterminologies.gov.au/integration/v2/fhir/ValueSet/australian-indigenous-status-latest

But I’m not sure of the use case for that (which is why we haven't done it), but there may be one.

I hope that clarifies what we've done and why. I guess the questions now are

  • do we want the "url" element to be version specific, or track "major" version as our CI team requested (and is currently implemented)? Their use case of having more stable binding points to reduce IG version churn makes sense to me, it is looser coupling.

and then related but not wholly dependent

  • do we want resolvable URLs for version specific (e.g. 1.0.0) versions of the ValueSets (regardless of whether that is chosen to be the "url" element value)?
  • do we want resolvable URLs for latest major versions (e.g. 1.x.x) of the ValueSets (regardless of whether that is chosen to be the "url" element value)?
  • do we want resolvable URLs for the "latest" version of ValueSets across all versions?

Sorry...I said it was complicated and there's a few trade-offs involved...

Finally a last thought (sorry this has turned into an essay). Say we have versions 1.0.0, 1.0.1 and 2.0.0 of the australian-indigenous-status ValueSet.

We could publish (maybe not all of these are useful?)

I've not thought that fully through, and perhaps it is really perverting the "url" identifier, but maybe that gives people the options they want? We want to make it easy for those defining IGs to reference the degree of specificity they want.

What are your thoughts?

view this post on Zulip Dion McMurtrie (May 04 2018 at 05:52):

OK, another update...sorry for the confusion, @Liam Barnes can probably answer this better than I can.

I think we do provide URLs for historical versions of the ValueSets when they are no longer the one referenced by the major version URL. So for example we have
https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1
which resolves to version 1.1.0 and has a "url" element of https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1

and we also have https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1.0.0
which resolves to version 1.0.0 and has a "url" element of https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1

We just don't have a resolvable URL for https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1.1.0 because it is currently resolvable at https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1 - but we could add https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1.1.0 as well.

Still, the "url" element value for all of these resources is https://api.healthterminologies.gov.au/integration/v2/fhir/CodeSystem/australian-states-territories-1 which doesn't match these URLs being resolved if that is an issue.

view this post on Zulip Brett Esler (May 04 2018 at 06:13):

Thanks @John Grimes and @Dion McMurtrie - I think we should have the version specific URL resolvable for the current version also - otherwise would have to change the reference if you wanted the specific version and it was no longer the latest...

view this post on Zulip Dion McMurtrie (May 04 2018 at 06:16):

OK, that makes sense. Do you think it is an issue that the URL wouldn't be the "url" element value of the resource? That doesn't seem to be a problem to me...but then I may be missing something

view this post on Zulip Danielle Tavares (May 04 2018 at 06:22):

I might be missing something but is one of the issues here that the reference is a logical reference (i.e. using valueSet.url) rather than a direct reference?

view this post on Zulip Grahame Grieve (May 05 2018 at 03:46):

it can also be a direct reference

view this post on Zulip Grahame Grieve (May 05 2018 at 03:46):

which is clearly what's needed in this case.

view this post on Zulip Grahame Grieve (May 05 2018 at 03:46):

but now I'm not sure what the exact request is

view this post on Zulip Liam Barnes (May 08 2018 at 00:25):

Most of everything you've described Dion is accurate, however most of our logical urls begin with https://heathterminologies.gov.au/fhir NOT https://api.healthterminologies.gov.au/integration/v2/fhir

As far as editorial rules go for version increments, again you've got this correct.

  • Patch version increments when there is an "insignificant" change e.g. typo change to that does not affect codes/display values, update resource description
  • Minor version is incremented when there is a significant non-breaking change e.g. addition of a new concept, inactivation of a concept, change to a display that doesn't change the meaning of the concept, etc.
  • Major version incremented when there is a significant breaking change e.g. any change that means concept permanence isn't maintained (removal of a code, description change altering the meaning of a concept). Where possible and in our control we will always try to maintain concept permanence.

view this post on Zulip Liam Barnes (May 08 2018 at 05:51):

It just occurred to me that I should have made those editorial rule examples more about value sets than code systems, but the same principles apply. A minor version increment may occur if there are additional members included or those members are inactivated in the code system. A major version increment would occur if a member is removed.

Last updated: Apr 12 2022 at 19:14 UTC


An HL7 Website -