VocMnt-CodeSysRev
Code System Revisions [Not fully exposed in application]
A code system revision can either create (register) a new code system or update an existing system.
Registering a New Code System [Not exposed in application]
The registerCodeSystem element is used to register a new external, internal or external/internally coded code system with the HL7 RIM vocabulary. The attributes of the registerCodeSystem entry are described below.
| codeSystemName | The full name used to describe the code system. |
|---|---|
| codeSystemMnemonic | A short mnemonic used to represent the code system within the HL7 vocabulary. The mnemonic must be unique. |
| codeSystemType | (see table below) |
| codeSystemOID | the official ISO Object Identifier (OID) of the code system. The OID can be omitted when vocabularyRevision.documentStatus is anything other than Final. The codeSystemOID must be explicitly stated before the code system can be registered in the official RIM database.
If the code system OID is omitted, it will be assigned an available number from the HL7 example root branch (2.16.840.1.113883.19). A number will be assigned from the 2.16.840.1.113883.19.5 branch for internal code systems and the 2.16.840.1.113883.19.6 branch for External systems. |
| codeSystemType | Meaning |
|---|---|
| I | (Internal) The code system is created and maintained by HL7 (default) |
| E | (External) The code system is created and maintained by an outside party and is not carried in the HL7 tables |
| EI | (External/Internally maintained) The code system is created and maintained by an outside party, but a copy is carried within the HL7 tables for convenience. |
Code System Description
The description element immediately follows the ballotStatus if it exists. Otherwise it is the first element in the code system registration block. It is optional and describes the intent or purpose of the code system revision.
The example above registers a new Beer and Flavor Classification code system under the mnemonic BEERS. The entry has passed RIM harmonization with 17 for, 4 against and one abstention. The code system is Internal by default. Because an OID isn’t supplied, an OID will automatically be generated from the 2.16.840.1.113883.19.5 branch.
The above example registers the LOINC code system as an external entry under the mnemonic “LOINC” with the OID “2.16.840.1.113883.6.1”
3.1.2 Adding Concept Codes to a Code System [Exposed under VS in application (3)]
The registerCodeSystem operation allows concept codes to be added to the newly registered system.
Figure 11 – addCodesToCodeSystem - 110
The first component of addCodesToCodeSystem is an optional ballotStatus as described above. Codes may either be added underneath an already existing concept code or as a completely new hierarchical node. In this context “under” is used to imply subsumption. If, for example, Pale Ale is a kind of Ale, the code for Pale Ale would occur “under” the code for Ale.
It is anticipated that the underCode option will be used primarily when rearranging existing code systems. Its attributes are:
Figure 12 - underCode attributes -120
conceptCode The concept code of an existing parent node
conceptName A valid designation for the parent node. conceptName is optional, but will be validated if it is supplied.
The newCode node identifies a new concept code to be added to the code system.
Figure 13 - newCode attributes-130
conceptCode The new concept code to be added to the code system. The code must not already exist in the system.
conceptName A valid designation for the concept code is required.
Each newCode entry can also include a description of the intent and purpose of the code. The description element is optional, but strongly recommended. Additional newCode entries may be nested underneath other entries as needed. The figure below shows a sample set of newCode entries.
<addCodesToCodeSystem>
<ballotStatus action="Proposed"/>
<newCode conceptCode="1001" conceptName="ALE">
<description>The name which was given to a brew drink acquire from the ancient Celts Anglo-Saxon origin but today synonym to high brew beer.</description>
<newCode conceptCode="1002" conceptName="PALE ALE">
<description>Light amber colouring, with, abundant hop and fairly dry. Slightly bitter. Below 5ø alcoholic contents. Served at cellar temperature.</description>
</newCode>
<newCode conceptCode="1003" conceptName="BITTER ALE">
<description>Very dry beer and decisively bitter. Distinct malt taste and aroma. Dark coppery colour. Low carbon dioxide contents. 3-4 alcoholic contents. Traditionally drafted.</description>
</newCode>
<newCode conceptCode="1004" conceptName="LIGHT ALE">
<description>Lower alcoholic contents than the bitter. Traditionally dunk out of a bottle.</description>
</newCode>
</newCode>
<newCode conceptCode="1005" conceptName="PORTER">
<description>Originated in London. Both it's dark brown colour and it's characteristic bitter taste is due to the roasted barley and not to the malt. The bitter taste increased with the high hop quantities which makes it also sour.</description>
</newCode>
<newCode conceptCode="1006" conceptName="STOUT">
<description>It is thicker and richer than the Porter, also made with roasted barley and not malt. National Irish beer and very sour, dark with a rich creamy froth.</description>
</newCode>
<newCode conceptCode="1007" conceptName="BITTER STOUT">
<description>Very dry and distinctively bitter. Only sold in Ireland</description>
</newCode>
</addCodesToCodeSystem>
Figure 14 - Sample addCodesToCodeSystem entry
The above example adds four new concept codes as “root nodes” – 1001 (ALE), 1005 (PORTER), 1006 (STOUT) and 1007 (BITTER STOUT). It also adds concept codes 1002 (PALE ALE), 1003 (BITTER ALE) and 1004 (LIGHT ALE) as children of the ALE node.
<codeSystemRevision>
<selectCodeSystem codeSystemMnemonic="BEERS">
<addCodesToCodeSystem>
<underCode conceptCode="1006" conceptName="STOUT">
<newCode conceptCode="1008" conceptName="SWEET STOUT">
<description>Dark brown colour with a sweeter taste, malted, slightly spicy. </description>
</newCode>
<newCode conceptCode="1009" conceptName="MILK STOUT">
<description>Sweet stout version with added milk sugar to soften the sour taste. </description>
</newCode>
</underCode>
</addCodesToCodeSystem>
</selectCodeSystem>
</codeSystemRevision>
Figure 15 - Sample addCodesToCodeSystem on existing system
The example above shows how concept codes can be added underneath an existing concept code in an existing code system. In the example we add two new concept codes – 1008 and 1009 as children of the existing concept code 1006 (STOUT).
3.1.3 Adding Print Names to a Concept Code [Exposed under VS in application (3)]
Both the registerCodeSystem and the selectCodeSystem branches allow additional print names to be added to existing concept codes.
Figure 16 – addPrintNameToCode - 160
Each addPrintNameToCode entry can have its own ballot status (see: section 2.2). If omitted, the ballotStatus of the containing element will be used.
Figure 17 - addPrintNameToCode attributes-170
conceptCode The concept code to add the new print name to
conceptName A valid previous designation for concept code. Optional, but will be validated if it is supplied
newPrintName The print name to be added to the concept code
languageCode The language code for the print name. Default is “en” for English
isPreferred Flag indicating whether the print name is preferred for the language. Default is “true”.
If the isPreferred flag is “true”, the default value, all other print names for the same concept code and language will have their isPreferred flags set to “false”.
<codeSystemRevision>
<selectCodeSystem codeSystemMnemonic="BEERS">
<addPrintNameToCode conceptCode="1004" conceptName="LIGHT ALE"
newPrintName="Pils" languageCode="de"/>
<addPrintNameToCode conceptCode="1004" newPrintName="Lager"
languageCode="de" isPreferred="false"/>
</selectCodeSystem>
</codeSystemRevision>
Figure 18 - Sample addPrintNameToCode
The example above adds two new German print names to concept code 1004 – LIGHT ALE. The first name, Pils, is the preferred German name.
3.1.4 Adding Properties to a Concept Code [Not exposed in application (1)]
Properties such as “openIssue”, “appliesTo”, “howApplies”, etc. can be added to concept codes during either the code system registration or code system update phases.
Figure 19 – addPropertyToCode-190
addPropertyToCode can have its own ballotStatus (see section 2.2) or can inherit the ballotStatus from the containing entry. The concept code, property id and language code are defined as attributes (see below). The property value itself is entered in the property element.
Figure 20 - addPropertyToCode attributes-200
conceptCode The concept code to add the property to
conceptName The preferred name of the code. Optional, but validated if supplied.
propertyId The unique identifier of the property to be added
language The language of the property. Default is “en” if not supplied.
<addPropertyToCode conceptCode="1007"
conceptName="BITTER STOUT"
propertyId="appliesTo">
<ballotStatus action="Withdrawn" vote="3-12-1"/>
<property>Colds and whatever else ails you</property>
</addPropertyToCode>
Figure 21 - addPropertyToCode sample
The above example adds an appliesTo property to concept code “1007”. The sample also shows an example of a negative vote – probably because the appliesTo property was being badly misused.
3.1.5 Defining Relationships between Concept Codes
Additional relationships other than subsumption may be asserted to exist between concept codes. As an example, one may want to assert that one concept code occurs “before” a second in a basic ordering. Relationships can be added to concept codes during either the code system registration or code system update phases.
Figure 22 – addConceptRelationship -220
As with the other operations, addConceptRelationship can have own ballotStatus see section 2.2 or can inherit the ballotStatus from the containing entry. The addConceptRelationship attributes define the relationship to be added:
Figure 23 - addConceptRelationship attributes - 230
parentCodeSystemMnemonic The mnemonic identifying the code system that holds the parent code. Optional. If blank, is assumed to be the code system established by the parent registerCodeSystem or selectCodeSystem.
parentCode The concept code that occurs on the “left hand” or parent side of the relationship
parentName A valid designation for the parent code. Optional but validated if present
relationship A valid relationship code (e.g. smallerThan)
childCodeSystemMnemonic The mnemonic identifying the code system that holds the child (related) code. Optional. If blank, is assumed to be the code system established by the parent registerCodeSystem or selectCodeSystem.
childCode The concept code that occurs on the “right hand” or child side of the relationship
childName A valid designation for the child code. Optional but validated if present.
<addConceptRelationship parentCode="1002" parentName="LIGHT ALE" relationship="smallerThan"
childCode="1003" childName="BITTER ALE"/>
Figure 24 - Sample addConceptRelationship entry
The above example asserts that concept code “1002” is “less than” concept code “1003” in an ordinal sense.
3.2 Modifying an Existing Code System [Not fully exposed in application (2)]
It is also possible to modify the contents of a previously registered code system. As with new code systems, it is possible to add new concept codes to the code system, new print names or properties to concept codes, and new relationships between concept codes. In addition it is also possible to modify the properties of the code system itself, modify or remove print names, descriptions, properties and relationships. It is also possible to retire concept codes from code systems and adjust subsumption relationships.
Figure 25 – selectCodeSystem-250
selectCodeSystem has an optional ballotStatus element that can be used to record the vote on the entire modification (see section 2.2). It has a single attribute, codeSystemMnemonic, that selects the code system to be modified.
Figure 26 - selectCodeSystem attributes-260
codeSystemMnemonic The HL7 mnemonic code for the code system to be selected
The first four selectCodeSystem operations (with a gray background in the figure 2 above) have been discussed under registerCodeSystem (above), where they also apply.
<codeSystemRevision>
<selectCodeSystem codeSystemMnemonic="BEERS">
<ballotStatus action="PassedWithChanges" vote="12-1-0">
<note>Author will sample all changes first</note>
</ballotStatus>
Figure 27 - Sample selectCodeSystem element
The above example selects the “BEERS” code system for modification. Unless otherwise noted, all of the changes within the selection were passed by a 12-1-0 vote (the author being the single negative vote) with the provision that author will sample all of the changes before they are officially recorded.
3.2.1 Modifying the Code System Mnemonic, Name or Description [Not exposed in application (1)]
The modifyCodeSystem element is used to update the properties of the code system itself.
Figure 28 – modifyCodeSystem-280
modifyCodeSystem has two optional elements. The first, ballotStatus, defines the status of the modification if it is different than the status as it occurs on the selectCodeSystem node. The second optional element, description, is used to add, update or remove the existing code system description. If the description element is not supplied, the existing code system description is unchanged. The name of a code system can be changed as well, using the codeSystemName attribute.
Figure 29 - modifyCodeSystem attributes-290
codeSystemName If present, the code system name will be updated to this value
newOID If present, the code system OID will be updated to this value
<selectCodeSystem codeSystemMnemonic="BEERS">
<ballotStatus action="PassedWithChanges" vote="12-1-0">
<note>Author will sample all changes first</note>
</ballotStatus>
<modifyCodeSystem codeSystemName="Castello Beer and Flavor Classification"/>
</selectCodeSystem>
Figure 30 - Sample modifyCodeSystem entry
The above example changes the BEERS code system name from what it was previously (Beer and Flavor Classification) to “Castello Beer and Flavor Classification. 3.2.2 Updating the Print Name of a Concept Code [Exposed under VS in application (3)]
Print names for concept codes can be removed or updated, and the setting for which print name is preferred for a given language can be changes as well.
Figure 31 – updateCodePrintName-310
updateCodePrintName includes an optional ballotStatus that reflects the status of the change if it is different from that of the entire revision.
Figure 32 - updateCodePrintName attributes -320
conceptCode The concept code to be changed
oldPrintName The original print name
newPrintName The new print name. If omitted, the name isn’t changed. If present, but empty, the print name is removed.
languageCode The language code for both the old and new print names. Default: en. Note: the language of a print name cannot be changed. If this is necessary, the print name for one language must first be removed and then re-added under the second language.
isPreferred true means that this print name is the preferred one for the supplied language. Setting this to “true” sets all other isPreferred flags to “false” to for the given concept code/language.
<selectCodeSystem codeSystemMnemonic="BEERS">
<updateCodePrintName conceptCode="1004"
oldPrintName="LIGHT ALE" newPrintName="Light Ale"/>
<updateCodePrintName conceptCode="1004"
oldPrintName="Pils" newPrintName="Kölsch" languageCode="de"/>
<updateCodePrintName conceptCode="1004"
oldPrintName="Lager"
languageCode="de" isPreferred="true"/>
<updateCodePrintName conceptCode="1004"
oldPrintName="Kölsch" newPrintName="" languageCode="de"/>
</selectCodeSystem>
Figure 33 - Sample updateCodePrintName entries
The first entry above changes the print name of concept code “1004” from “LIGHT ALE” to “Light Ale”. The second entry changes the German print name for concept code “1004” from “Pils” to “Kölsch”. Note that this operation would fail if there wasn’t already a German print name “Pils”. The third entry changes “Lager” to be the preferred German print name if it isn’t already. If it is, this operation would still succeed. The fourth entry removes the “Kölsch” print name completely – a somewhat odd request since we went to all the trouble of changing it a couple lines earlier.
3.2.3 Changing the Description of a Concept Code [Exposed under VS in application (3)]
The description of a concept code may be added, modified or removed using the updateCodeDescription element.
Figure 34 - updateCodeDescription
As with all updates, updateCodeDescription can have its own ballotStatus if needed to reflect special cases. It has an optional oldDescription element that can contain the description that is being changed and a newDescription element that contains the revised description or can be empty if the description is to be completely removed. If present, the oldDescription will be validated against the database before the change is performed.
Figure 35 - updateCodeDescription attributes
conceptCode The concept code that the change is being applied to
conceptName A valid designation for the concept code. Optional, but will be validated if supplied.
<codeSystemRevision>
<selectCodeSystem codeSystemMnemonic="BEERS">
<updateCodeDescription conceptCode="1004" conceptName="Light Ale">
<oldDescription>Lower alcoholic contents than the bitter. Traditionally dunk out of a bottle.</oldDescription>
<newDescription>Lower alcoholic contents than bitter.</newDescription>
</updateCodeDescription>
</selectCodeSystem>
</codeSystemRevision>
Figure 36 - Sample updateCodeDescription
The example above removes the second sentence from the “Light Ale” description. Note that the preferred name is “Light Ale” rather than “LIGHT ALE” because of an update that occurred earlier in both this document and the actual XML update source. 3.2.4 Moving a Code in the Subsumption Hierarchy [Exposed under VS in application (3)]
Concept codes can be rearranged within the concept subsumption hierarchy. moveCode can be used to assert that one concept code is a “kind of” or “is implied by” a second concept code. It can also remove this assertion.
Figure 37 – moveCode -370
As with all update operations, moveCode has a separate, optional ballotStatus node. The moveCode attributes specify the operation to be performed:
Figure 38 - moveCode attributes
conceptCode The code of the concept to be moved.
conceptName A valid designation for the concept to be moved. Optional, and if supplied it will be validated against the database before the operation occurs.
fromParentCode The current direct parent of the concept code, if any. This attribute should be omitted if conceptCode doesn’t currently occur under any other node.
fromParentName A valid designation for the from parent code. Optional, but validated if supplied.
toParentCode The new parent of conceptCode. If omitted, conceptCode no longer has a parent in the subsumption hierarchy.
toParentName A valid designation for the to parent code. Optional, but validated if supplied.
<selectCodeSystem codeSystemMnemonic="BEERS">
<moveCode conceptCode="1008" conceptName="SWEET STOUT"
fromParentCode="1006" fromParentName="STOUT"/>
<moveCode conceptCode="1006"
toParentCode="1008" toParentName="SWEET STOUT"/>
</selectCodeSystem>
Figure 39 - Sample moveCode entries
In the above example, concept code “1008” (SWEET STOUT) is first removed as a child of “1006” (STOUT). If this operation succeeds, both STOUT and SWEET STOUT would be root nodes in the subsumption hierarchy. The second part the operation asserts that 1006 (STOUT) is a kind of 1008 (SWEET STOUT). Note that all other entries in the subsumption hierarchy remain unchanged (e.g. 1009 – MILK STOUT) remains a kind of STOUT throughout.
3.2.5 Retiring a Concept Code [Exposed under VS in application (3)]
While a concept code may never be reused within a code system, it may be “retired” from active use.
Figure 40 – retireCode - 400
As with all operations, retireCode may be accompanied by an optional ballotStatus. The attributes of retireCode determine what actually happens:
Figure 41 - retireCode attributes
conceptCode The code of the concept to be retired
conceptName A valid designation for the concept to be retired. Optional, but validated if supplied.
replacementCode A new or existing concept code that will replace the retired code. If new, all of the retired code’s names, properties and relationships are copied over to the new code. If replacementCode already exists, the current concept code’s properties, etc. are dropped.
replacementName The name of the replacement concept code. If the replacement code exists and this name is supplied it will be validated. If the replacement code is new and this name is supplied, it will become the preferred name for the replacement code.
completeDelete <<Editor is Uncertain as to what this means>>.
3.2.6 Removing Existing Concept Relationships [Not exposed in application (1)]
It is also possible to undo relationships that have previously been asserted using the addConceptRelationship node.
Figure 42 – removeConceptRelationship -420
Like all operations, removeConceptRelationship can have a ballot status entry that overrides the outside status. removeConceptRelationship has the following attributes:
Figure 43 - removeConceptRelationship attributes
parentCodeSystemMnemonic The mnemonic identifying the code system that holds the parent code. Optional. If blank, is assumed to be the code system established by the parent registerCodeSystem or selectCodeSystem.
parentCode The left hand or parent side of an existing relationship entry
parentName A valid designation for the parentCode. Optional but validated if present.
relationship The code for the existing relationship (e.g. smallerThan)
childCodeSystemMnemonic The mnemonic identifying the code system that holds the child code. Optional. If blank, is assumed to be the code system established by the parent registerCodeSystem or selectCodeSystem.
childCode The right hand or child side of an existing relationship entry
childName A valid designation for the childCode. Optional but validated if present.
