Stream: terminology
Topic: CodeSystem identification and versioning
Vitaly Rodionov (Oct 08 2021 at 09:26):
Hello!
What are the best practices for CodeSystem versioning?
More specificaly that are the rules for identification of different versions of a codesystem?
CodeSystem has these attributes for identification and versioning:
id Logical id of this artifact
url Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system)
identifier Identifier Additional identifier for the code system (business identifier)
version Business version of the code system (Coding.version)
That of these should stay the same and that of these should acquire new values then the codesystem is getting a new version?
For example:
URL should be "globally unique", but is it for the codesystem or for the codesystem version?
The same goes for identifier - is it a "business identifier" for the codesystem or for the codesystem version?
I found some inconsistency in identification and versioning of standard codesystems published in the FHIR-specification.
Some examples:
Here url and id are the same between versions but oid is different.
"id" : "FHIR-version",
"url" : "http://hl7.org/fhir/FHIR-version",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:2.16.840.1.113883.4.642.4.1310"
}],
"version" : "4.0.1"
"id" : "FHIR-version",
"url" : "http://hl7.org/fhir/FHIR-version",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:2.16.840.1.113883.4.642.1.1310"
}],
"version" : "4.6.0"
Here url, id, oid are different but version is the same despite it's clearly a new version of the codesystem.
"id" : "v2-2.4-0006",
"url" : "http://terminology.hl7.org/CodeSystem/v2-0006|2.4",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:2.16.840.1.113883.18.8"
}],
"version" : "0006",
"name" : "v2.0006.2.4",
"title" : "v2 table 0006, Version 2.4",
"id" : "v2-2.1-0006",
"url" : "http://terminology.hl7.org/CodeSystem/v2-0006|2.1",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:2.16.840.1.113883.18.7"
}],
"version" : "0006",
"name" : "v2.0006.2.1",
"title" : "v2 table 0006, Version 2.1",
So what is the correst way to identify and version codesystem?
For example we have two versions of some codesystem:
https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040/version/1.0
https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040/version/2.1
(the requerment is to store both versions of the codesystem on the same fhir-server)
Some posible variants of describing these as a fhir-resource are:
(1) id, url, version - different, oid - same
"id" : "1040-v-1-0",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040/version/1.0",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040"
}],
"version" : "1.0"
"id" : "1040-v-2-1",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040/version/2.1",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040"
}],
"version" : "2.1"
(2) id, url, oid, version - all different
"id" : "1040-v-1-0",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040/version/1.0",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040.1.0"
}],
"version" : "1.0"
"id" : "1040-v-2-1",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040/version/2.1",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040.2.1"
}],
"version" : "2.1"
(3) only version is different (this variant will probably work only with replacement of codesystem?)
"id" : "1040",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040"
}],
"version" : "1.0"
"id" : "1040",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040"
}],
"version" : "2.1"
Lloyd McKenzie (Oct 08 2021 at 13:13):
The combination of url + version are expected to be unique on a given server. identifier generally corresponds to url, though it's not prohibited for it to include version as well. The id is server-assigned and SHALL be unique on a given server. It doesn't need to have any correlation to the others.
There are no specific rules about when to create a new 'version' (aka 'release') of a code system, nor are there global rules about what changes can be made to a code system before it's necessary to call it a distinct code system. (FHIR has preliminary rules for its own code systems, which is essentially "anything goes until the code system is normative, after that 'inter-version compatibility rules apply'".
Vitaly Rodionov (Oct 08 2021 at 13:45):
Thank you. That makes the situation a little bit clearer.
So, basicaly, 'url' doesn't have to be "globally unique" and there can be several codesystems with the same 'url' as long as they all have different version values, right?
Does that mean that for my example we can have the following codesystem resources on a server:
"id" : "1040-v-1-0",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040"
}],
"version" : "1.0"
"id" : "1040-v-2-1",
"url" : "https://nsi.rosminzdrav.ru/#!/refbook/1.2.643.5.1.13.13.11.1040",
"identifier" : [{
"system" : "urn:ietf:rfc:3986",
"value" : "urn:oid:1.2.643.5.1.13.13.11.1040"
}],
"version" : "2.1"
They have different id and combination of url+version is also unique.
Is that correct?
Rob Hausam (Oct 08 2021 at 15:27):
We worked out some rules for when to create a new code system version vs. creating a new code system in the "V2 Tables" project that the Vocabulary WG did a while ago. As Lloyd suggests, it wouldn't necessarily to required for anyone to follow those same rules, but I think they generally should be useful and could certainly serve as a guide. Now I'll just need to recall or find where we have them documented. :)
Lloyd McKenzie (Oct 08 2021 at 16:45):
@Vitaly Rodionov Yes, that's completely legal. The gist is that with "conformance" resources - those that have a 'url' and 'version' element, there could be multiple versions under active maintenance, and so we need to support multiple instances with the same url (so long as they have distinct versions).
Robert McClure (Oct 12 2021 at 16:00):
Agree with Lloyd, and also the issue regarding when is it a version versus a new code system is in part tied to meaning permanence for the concepts in the code system, IE: you are expected to have meaning consistency version to version for any concepts with the same code identifier across the versions. If you need to break that rule, you have a new code system, not a new version.
Rob Hausam (Oct 12 2021 at 19:02):
Yes, that's the primary rule.
Bill Harty (Jan 20 2022 at 21:39):
@Rob Hausam Above you reference some rules/guidance for new version vs. new code system in the "V2 Tables". Can you point me at that, or anything similar? We're working on additions/modifications to BlueButton valuesets and looking for guidance in terms of versioning.
Rob Hausam (Jan 21 2022 at 22:58):
@Bill Harty Hi, Bill. Sorry it's taken me a little while to respond (now that the WGM has ended). I'll have to see if I can track down our documentation on this. The "V2 tables" project work was done before all of our documentation in GForge was archived and should have been moved to Confluence, but I'm not sure where that ended up (or if we have something else that would cover it, too). I didn't find anything yet on a (admittedly rather quick) search. Maybe @Ted Klein will recall?
Ted Klein (Jan 21 2022 at 23:15):
@Bill Harty Are you referring to the concept codes holding the metadata for Version 2 tables objects carried in the THO code system "v2tables.xml", or are you talking about the versions of the code systems that were created to hold the HL7 defined coded values shown in the v2 publication Chapter 2C for Version 2 tables?
Rob Hausam (Jan 21 2022 at 23:49):
@Ted Klein Ted, I think Bill is looking for the set of rules that we used to decide when to create a new code system vs. a new version of an existing code system. We documented that for the "v2 tables" project, so I was suggesting to look there. But we may have that (or the equivalent) somewhere else, too?
Ted Klein (Jan 22 2022 at 00:29):
Yes that was all on the old wiki for the project; it predated the use of the Atlassian tools at HL7. I don't now if that stuff was archived or saved or not. It should have been...but that might be in hindsight now. The basic rule was as per Jim Case: additions of new codes or changes to descriptions or display names were version updates. Removal or wholesale changes in codes were a new code system. That was not done all that many times.
Bill Harty (Jan 25 2022 at 01:39):
This is helpful, thanks for the info - that seems to line up with comments earlier in this thread. Regarding version changes (e.g. additions, description changes), is there guidance on how to populate a coding element to reflect version? One option would be to keep coding.system static and populate coding.version to correctly reflect the version e.g. coding.system = "http://acme.org/valueset/xyz" and coding.version = "2.0". But we've had internal discussions about embedding version in the url e.g. coding.system = "http://acme.org/valueset/xyz/v2". But in reality it seems that neither of those options are commonplace in the field. Seems like most implementers don't provide any version identifiers in a coding, maybe because version changes are generally non-breaking/backwards compatible, so it's not critical to worry about it? Thanks again for any thoughts/guidance.
Rob Hausam (Jan 25 2022 at 17:41):
@Bill Harty I think that, when you actually need it, Coding.version is the "right" (or at least likely the best) answer. But, as you say, many times it really isn't needed, if the code system is "well-behaved" in regard to concept identifiers and definitions. It's discussed here for the Coding data type.
Last updated: Apr 12 2022 at 19:14 UTC
