Code Systems owned and maintained by HL7 and its affiliates. This includes the following special code systems: UTG concept properties, concept domains, and V2 Tables
HL7 Code Systems Versioning
Stakeholders who assign the version
|Version assertion||Version represents||Version value format||Initial version for new instances|
|Yes||CodeSystem.version value||The version of coding system defined by the HL7 Code System artifact. For example, when using a concept from this Code System in a FHIR coding data element the version will be used in the Coding.version sub-element.||MAJOR.MINOR.PATCH e.g. 1.0.0||1.0.0|
Version changes rules
Data element changes
Data Element Name
|New Artifact||No Change||Major||Minor||Patch||Comments||Task Force Sign Off / Date|
See https://confluence.hl7.org/pages/viewpage.action?pageId=91995515#SpecifyingtheDetailsInsidetheProposal-CodeSystemMetadata for how CodeSystem.id and CodeSystem.url relate.
CodeSystem.id is strongly related to CodeSystem.url.
Changing id (caused by change to url) would result in a new CodeSystem.
|CodeSystem.meta.versionId||x||We need to revisit use cases for these meta data elements. Punting for now.||2022-08-24|
|CodeSystem.meta.source||x||Suggest excluding this in the future (such as when we have profiles)||2022-08-24|
|CodeSystem.meta.security||x||Suggest excluding this in the future (such as when we have profiles)||2022-08-24|
|CodeSystem.implicitRules||x||Suggest excluding this in the future (such as when we have profiles)||2022-08-24|
|CodeSystem.language||x||Should pursue a policy that if a language is asserted on the Code System, then all versions must use that same language. Should only set this in the initial instance of the resource and fixed from thereon out, or not include it at all.||2022-08-24|
|CodeSystem.url||x||Noting that urls have changed when code systems have been migrated from FHIR to THO.||2022-08-24|
|CodeSystem.identifier||x (changing, removing)||x (adding)|
Blanket statement: Cannot change or remove a CodeSystem.identifier. You can add them, but once you add them they are immutable. You must create a new CodeSystem for identifier changes or to remove an identifier. Extreme care must be taken with identifiers.
Note that best practice is to maintain identifiers and so we do not anticipate them being removed.
These identifiers are considered authoritative for the CodeSystem and deprecating them (method is not currently set/clear) is considered a change and thus the CodeSystem as a whole needs to be deprecated.
Note that the current plan for adding IRI stems involves adding them as identifiers.
Discussed treating this element as a secondary identifier (to urls). CDA/V3 uses OID as a primary identifier, however.
Does changing url force you to change identifier, and vis versa?
Identifiers in the Code Systems are authoritative you must use, and NamingSystem identifiers track additional identifiers.
Recommended that extension be defined in THO or core spec to document which artifact supersedes the artifact. Since New OID = New CS, it is up to code system owner to deprecate, but it is recommended.
|CodeSystem.version||-||-||-||-||-||Depends on all rules here.||2022-08-31|
|CodeSystem.date||-||-||-||-||-||Date cannot be changes unless other elements are changed. Version will be incremented based on changed elements.||2022-08-31|
|CodeSystem.publisher||x||Should all be a standard value for HL7 (we need to recommend that a fixed value be chosen for HL7 and everyone must use it). Once set, there no longer needs to be a versioning rule.||2022-08-31|
|CodeSystem.contact||x||Recommendation might be to have contact be THO team.||2022-08-31|
Major unless only change is improved clarity or perform editorial corrections.
|x||Recommend use of useContext be clarified||2022-08-31|
Not Currently In Use for UTG.
Recommendation: Should decide what the intent of this element is within THO, could consider exclusion
|CodeSystem.purpose||x||Not Currently In Use for UTG||2022-09-07|
|x||We disagreed with previous note of "Minor, unless change from unencumbered to encumbered."||2022-09-07|
|CodeSystem.approvalDate||Added in R5|
|CodeSystem.lastReviewDate||Added in R5|
|CodeSystem.effectivePeriod||Added in R5|
|CodeSystem.topic||Added in R5|
|CodeSystem.author||Added in R5|
|CodeSystem.editor||Added in R5|
|CodeSystem.reviewer||Added in R5|
|CodeSystem.endorser||Added in R5|
|CodeSystem.relatedArtifact||Added in R5|
x (changing base, removing)
Pro-forma in UTG, Cannot Change Value.
Recommend that TSMG come up with rule for using this data considering canonical vs. uri and if version should be asserted. Should either go versioned or versionless and not switch between the two.
Handle with canonical vs. uri only cases in this policy.
Might want to consider tooling that programatically creates all codes Value Sets.
Versionless = only add and remove
Versioned will change with change of version of Code System
|CodeSystem.versionNeeded||x (if changing or removing value)||x (if adding value)|
TSMG should suggest policy or guidance that going from F to T may be a new code system . Unsure what it means if absent. This should really be a mandatory element.
When going from unvalued to valued, it should be a major change. Flip flopping is new code system.
|CodeSystem.content||x (changing value)|
We have some code systems that are marked as complete, but are actually not, such as http://build.fhir.org/ig/HL7/UTG/CodeSystem-v2-0140.html. Table 0005 is a fragment as well.
TSMG should consider whether example content should be in THO, but for now we assume they will be supported. Value should either be complete or example and should be fixed for the life of the code system. Changing is new code system.
|CodeSystem.supplements||x (if supplement is supplementing entirely new cs)||x (changing to reference new version of cs being supplemented i.e., the versioned part of the canonical value)|
TSMG needs policy on supplementing HL7 code systems. Need justification of changing supplement over changing. Changes could be made directly to the code system themselves. Affiliate could make supplement for an external code system
|CodeSystem.count||-||-||-||-||-||Any change would be based on change to CodeSystem.concept||2022-09-14|
|CodeSystem.filter (all subelements)||x (if changing or removing)||x (if adding)||Not Currently In Use for UTG||2022-09-14|
|CodeSystem.property (including CodeSystem.concept.property.code and .value)||x|
Major for Concept Status and defining property changes (like isSelectable), status changes to/from Active to Retired, Active→Backwards Compatible, addition of language translations of the text bits (print names, descriptions, etc.).
|CodeSystem.concept (and all subelements)||x||All changes to concepts by default are an increment of the major number. Any proposed change could include a proposal to change the minor number instead if the change is asserted to be minor in the change proposal.||2022-09-14|
|Are there special or different rules about certain 'special' code systems, such as UTG concept properties, or concept domains, or V2 Tables?||x||We do not need special rules but should be clear about these in scope/objective||2022-09-14|
|New Artifact||No Change||Major||Minor||Patch||Comments||Task Force Signoff / Date|
|Artifacts with THO base moving from elsewhere in HL7 into THO||x|
Recommend that TSMG consider the following option for approach if version of artifact to be moved is not in format x.y.z
|Artifacts without THO base moving from elsewhere in HL7 into THO||x||2022-10-12|
|Changing the version of FHIR used by THO||-||-||-||-||-|
Changes would be driven by required element changes and then follow versioning policy above.
Recommend that TSMG consider adding an extension to declare the version of FHIR in all HL7 code systems now. That way this can be incremented when THO moves to a new version to make it clear which version of FHIR the resource is based on.
Addition, modification, or removal of extension value. Approach should be based on THO authorized extensions and a policy must be established for each of those that is controlled by TSMG.
Could also consider making it a major change across the board to handle more significant cases.
Also need to consider that most extensions are not rendered in THO at all.
|Modifier Extensions||-||-||-||-||-||Recommend that TSMG decide if we want to support modifier extensions at all (or declare which are acceptable). Could manage them through registry as well (which would require TSMG approval).||2022-10-12|
|Text (Narrative) generated by IG Publisher||-||-||-||-||-|
Change is based on the data elements that have changed.
Should ensure that THO supported extensions are accounted for when text is auto-generated.
|Text (Narrative) created by resource authors||-||-||-||-||-||Recommend that TSMG decide what do we want to happen if the text is not generated (such as being manually added by the author).||2022-10-12|
|contained||-||-||-||-||-||Recommend that TSMG ban them from THO. You will need to make the content available one way or another so it does not make sense.||2022-10-12|