Vocabulary Harmonization Tool
Contents
- 1 Background & First Steps
- 2 HL7 Vocabulary Maintenance Language - Documentation of XML Submission Format
- 2.1 Introduction to the Original VML and to the 2014 Extension
- 2.2 VML Extension in 2013-14
- 2.3 Vocabulary Revisions Proposal
- 2.4 Code System Revisions
- 2.4.1 Registering a New Code System
- 2.4.2 Modifying an Existing Code System
- 2.4.2.1 Modifying the Code System Mnemonic, Name or Description
- 2.4.2.2 Updating the Print Name of a Concept Code
- 2.4.2.3 Changing the Description of a Concept Code
- 2.4.2.4 Updating Property on a Concept Code
- 2.4.2.5 Removing Properties from a Concept Code
- 2.4.2.6 Moving a Code in the Subsumption Hierarchy
- 2.4.2.7 Retiring a Concept Code
- 2.4.2.8 Removing Existing Concept Relationships
- 2.5 Value Set Revisions
- 2.6 Concept Domain Revision
- 2.7 Appendices
- 3 Harmonization Tool Documentation
Background & First Steps
At the September 2007 WGM, Vocabulary & M&M "upped the ante" on the Vocabulary Harmonization Tool, by requiring that facilitators use this tool, if at all possible in preparing submissions for the November 2007 Harmonization Meeting and subsequent meetings. In exchange, we promised to put up a support page on the Wiki for this tool.
This is the beginning of that documentation. The initial contribution is a minor revision and posting of the instructions and examples for using the previous Vocabulary Submission tool that required preparing XML files that drove the updates.
The current Eclipse-based tool is, for the most part, a GUI application that creates and processes the XML submission files. Therefore the old documentation is a solid start for this documentation. It can be downloaded as "Vocabulary Tool Documentation" from the Vocabulary Tooling project on Gforge. Subsequent updating and editing will move the primary source to this site. GWBeeler 00:32, 23 September 2007 (CDT)
HL7 Vocabulary Maintenance Language - Documentation of XML Submission Format
- This section lists the "sections" of html documentation of the XML Vocabulary Submission capability and format that is the foundation of the Eclipse-based Harmonization Tool. The various document sections have been posted in individual Wiki pages for ease of maintenance which
Introduction to the Original VML and to the 2014 Extension
This document describes a formal, XML based language that can be used to create and maintain the HL7 Version 3 reference vocabulary. The immediate purpose of this language is to provide vocabulary facilitators a consistent and rigorous mechanism that can be used to specify HL7 vocabulary additions and updates. In 22014, this is the primary means of preparing vocabulary changes for inclusion in the HL7 Vocabulary. The files are processed from VML through the Access data base and to MIF using the VML Processing Widget and RoseTree.
using these tools, content changes expressed in these proposals are applied to the repository of vocabulary content in an Access data base in two ways:
- Processing with a Java vocabulary update program first created in 2006-7, and
- Execution of pre-defined Access update queries drawing data from source tables generated by XSLT transforms that convert the "extension" properties that have been defined (below).
The formal representation of the vocabulary content is expressed in HL7 Model Interchange Format (MIF) files. This expression is undertaken by the RoseTree application working from the Access data base as its sole, primary source.
In this specification, a vocabulary maintenance description consists of a sequential list of parametrized function calls such as RegisterCodeSystem, AddCodes, CreateValueSet, etc. Further, the approach here is to separate the maintenance task into three separate parts:
- Code Systems – A code system contains a set of unique concept codes. Each concept code serves as a token to represent a useful category or class as viewed from a particular perspective. The definition and organization of the tokens within a code system represents assertions about the organization of the corresponding categories and classes within a real world. A code system may also carry information about the various ways that the categories or classes are identified in different situations and languages, as well as additional defining and identifying information that serves to clarify the intended meaning of the tokens
- Value Sets – A value set represents a list of concept codes. Value sets are used to specify a set of possible values for one or more RIM-derived coded attributes.
- Concept Domains - A concept domain represents an abstract conceptual space that can be associated with RIM-derived coded attributes. A concept domain can be represented by one or more value sets, where each associated value set applies in a given context. Further, sub-sets of concept domains may, themselves, be represented as concept domains in a parent-child semantic hierarchy.
Each of the above parts is maintained separately, with the revisions to the code system(s) occurring first followed by changes to the value sets followed by any revisions to concept domain/value set associations that might be necessary.
VML Extension in 2013-14
Over time, it became clear that couple of functions were "missing" from the existing VML. Specifically, the ability to "update" or "remove" a property from a code. As these were required, the update to the Access tables was taken as a manually created update, which while quick was prone to errors.
Beginning about 2009, the need arose to add properties to coded concepts, value sets, concept domains, etc. that could not be documented in the structure of the Access data base. Because the existing Java-based update tool is tightly bound to the data structures of the existing data base, and because no current volunteeers were familiar with the code of the Java application, the "toolsmiths" were reluctant to change the data content existing tables. As an alternative, the extension properties were added through two sets of tables:
- A pair of tables that treat these properties as name/value pairs, and that identify the target of these properties by their type (such as "vakueSet") and their fully qualified name. These tables are:
- VCS_property_definition that defines the purpose and type of each if the properties represented in this fashion.
- VCS_object_property That contains the name/value pairs and the formal identifier of the object to which they apply.
- For several years, the management of the content of these tables required manual updates to the their content in Access.
- VCS_property_definition that defines the purpose and type of each if the properties represented in this fashion.
- A pair of tables that document the version history of the value sets and code systems in the data base. Each time there is a change to a particular code system or value set, its history records will document in which release-index the change occurred, the formal published release in which the change first appeared, who made the change, and a brief summary of the changes. These data will allow proper release and version management for these code systems and value sets when these updates are completed in the second half of 2014. The tables in which the version history are documented are:
- VOC_value_set_history. and
- VCS_code_system_history
- VOC_value_set_history. and
The VML Extension, begun in 2013 and completed (we hope) in 2014, works withe the VML Processing Widget to automate the manual update processes of properties (done in 2013) and automate the capture of value set and code system history. In both cases this is realized by adding new "process elements" to the VML. The "automation" with the VML Processing Widget is provided by combination of:
- ANT scripts (run from the command line)
- XSLT Transforms to split the "extensions" from the original VML to create a Vocabulary Update Table that can be imported into Access; and
- Predefined update queries (programmed in Access Visual Basic For Applications (VBA)) that use the update table to change content in the appropriate vocabulary tables.
As the each VML is processed by ANT:
- the VML file is split to isolate the "extensions" from the "traditional" VML and to create the update table from the extensions;
- Access is activated to process the SQL-based Update and then shut down
- The isolated traditional VML is processed to the same Access data base using the Java update program to establish the "traditional" updates.
Recognizing Extension Elements
For those that were familiar with VML, the majority of this document is "old news". In order to make the recognition of extension elements easier, the graphics that have been updated to include extension elements have a red or maroon star somewhere on the right of the diagram; the extension elements are outlined in red, and the textual headers are in red font.
Vocabulary Revisions Proposal
A Vocabulary Revision represents a related collection of updates to one or more code systems, value sets and/or concept domains. Each vocabulary revision proposal comes from a single HL7 committee and is represented by one primary contact person. The VocabularyRevision element has to be the outermost (first) element in any vocabulary submission.
A VocabularyRevision always begins with an editDescription element that describes the intent and purpose of the proposal. There are several textual elements in editDescription as shown below. The actual description should be recorded in the description element.
The attributes of the editDescription are listed below:
| creationDate | when the document was first created (format: yyyy-mm-dd). |
|---|---|
| proposalId | id should be unique within the committee submitting it. A committee id will be concatenated to get a "unique" id. |
| primaryContact | the name of the person responsible for the document |
| committee| | the committee identifier primarily responsible for the changes |
| documentStatus| | [Not exposed in application, and should be] see table below: |
| Status | Meaning |
|---|---|
| Proposed | The document is in the initial stages |
| Submitted | The document has been submitted for review by the appropriate committees. |
| Reviewed | The document has been reviewed by the appropriate committees and is awaiting harmonization. |
| Harmonized | The document has been reviewed and voted on by the RIM Harmonization Committee |
| Final | The document has been recorded in the official RIM database and can undergo no further changes. |
| Rejected | The document was not accepted at some stage in the process. |
The tools used to update the actual vocabulary tables won’t process Rejected status documents. In addition, warnings will be generated if Harmonized or Final documents contain Proposed ballotStatus action entries (described below).
Final and Harmonized submissions must also supply OID’s for all new code system registrations.
The sample above describes a new edit created on September 25, 2007 by Woody Beeler for the Methodology & Modeling committee.
NOTE: the application will not process a proposal that has no content in the <description/> element of editDescription.
Edit Versions
A vocabulary revision may also include one or more editVersion entries that track the history of the submission. editVersion is optional and must immediately follow the editDescription entry.
| changeDate | date that the submission was changed |
|---|---|
| author | name of the person making the change |
Ballot Status
ballotStatus reflects the current status of the document in terms of the RIM Harmonization process. A ballotStatus element can occur at multiple points throughout a vocabulary submission document, with the “innermost” status taking precedence. A ballotStatus has an optional note element that can be used to clarify the current state. ballotStatus has the following attributes:
The first component of a registerCodeSystem entry is the ballot status of the action. The ballotStatus entry is optional. If it is omitted, it defaults to the innermost surrounding ballotStatus. If, for example, the ballotStatus for addCodesForCodeSystem is omitted, the surrounding registerCodeSystem or selectCodeSystem ballotStatus would apply. If there is no surrounding ballotStatus, the status defaults to Proposed.
| action | the current status on this particular part of the submission as described by the table below |
|---|---|
| vote | the actual vote (format: yy-nn-aa) where yy is the number of yes votes, nn the number of no votes and aa the number of abstentions. The vote attribute applies to Passed, PassedWithChanges and Withdrawn actions |
| Action | Meaning |
|---|---|
| Proposed | The proposed revision has been proposed (default). |
| Passed | The revision has passed RIM harmonization |
| PassedWithChanges | The revision has passed RIM harmonization subject to the changes outlined in the note. |
| Tabled | The revision has been set aside and will be reconsidered at a future time. |
| Withdrawn | The revision has been withdrawn, voted down or otherwise has not been accepted. It cannot be reconsidered in this context. |
| NonVotingItem | The revision consists of technical changes that do not need to be voted on. |
Tabled and Withdrawn entries will not be processed by the tools used to update the RIM vocabulary database. In addition, Proposed items will be considered in error when the vocabularyRevision.documentStatus is Final.
Revisions
A list of revision entries follows the edit description and edit versions (if any) . Revision entries are applied in the order that they occur. A revision entry can create or modify a code system, a value set or a concept domain. The following tags identify revision entities:
- codeSystemRevision - [Not fully exposed in application] Register (create) a new code system or modify the contents of an existing code system.
- valueSetRevision- Create a new value set or modify the contents of an existing value set.
- vocabularyDomainRevision – Create or modify a concept domain.
The contents of these revision records are described in more detail in the following sections.
Revision records will be applied to the vocabulary database in sequential order. A typical sequence of revision records might consist of:
- Register a new code system and define its contents
- Create the value set (or sets) drawn from the code system
- Create the concept domain and connect it to the value sets.
Code System Revisions
A code system revision can either create (register) a new code system or update an existing system.
Registering a New Code System
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”
Adding Concept Codes to a Code System
The registerCodeSystem operation allows concept codes to be added to the newly registered system.
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:
| 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.
| 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.
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.
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).
Adding Print Names to a Concept Code
Both the registerCodeSystem and the selectCodeSystem branches allow additional print names to be added to existing concept codes.
Each addPrintNameToCode entry can have its own ballot status (see above). If omitted, the ballotStatus of the containing element will be used.
| conceptCode | The concept code to which the new print name is to be added. |
|---|---|
| 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.
The example above adds two new German print names to concept code 1004 – LIGHT ALE. The first name, Pils, is the preferred German name.
Adding Properties to a Concept Code
Properties such as openIssue, appliesTo, howApplies, etc. can be added to concept codes during either the code system registration or code system update phases.
addPropertyToCode can have its own ballotStatus 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.
| conceptCode | The concept code to which the property is to be added |
|---|---|
| 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. |
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.
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.
As with the other operations, addConceptRelationship can have its own ballotStatus or can inherit the ballotStatus from the containing entry. The addConceptRelationship attributes define the relationship to be added:
| 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. |
The above example asserts that concept code “1002” is “less than” concept code “1003” in an ordinal sense.
Modifying an Existing Code System
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.
selectCodeSystem has an optional ballotStatus element that can be used to record the vote on the entire modification. The first four selectCodeSystem operations (shown with a gray background in the figure above) have been discussed under registerCodeSystem (above), where they also apply. The remaining six operations are discussed in the following sub-sections.
selectCodeSystem has a single attribute, codeSystemMnemonic, that selects the code system to be modified.
| codeSystemMnemonic | The HL7 mnemonic code for the code system to be selected |
|---|
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.
Modifying the Code System Mnemonic, Name or Description
The modifyCodeSystem element is used to update the properties of the code system itself.
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.
| codeSystemName | If present, the code system OID will be updated to this value |
|---|---|
| newOID | If present, the code system OID will be updated to this value |
The above example changes the BEERS code system name from what it was previously (Beer and Flavor Classification) to “Castello Beer and Flavor Classification.
Updating the Print Name of a Concept Code
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 changed as well.
updateCodePrintName includes an optional ballotStatus that reflects the status of the change if it is different from that of the entire revision.
| 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. |
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.
Changing the Description of a Concept Code
The description of a concept code may be added, modified or removed using the updateCodeDescription element.
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.
| 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. |
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.
Updating Property on a Concept Code
Once a property has been added to a coded concept, that property may be updated using the updatePropertyOnCode' element.
As with other property setting elements, the value to which the property should be updated is documented as the content of a child property element.
| conceptCode | The concept code to which the property is attached |
|---|---|
| propertyId | The identifier (name) of the property to be updated. |
Removing Properties from a Concept Code
A property that has been added to a coded concept may be removed using the removePropertyFromCode element.
| conceptCode | The concept code to which the property is attached |
|---|---|
| propertyId | The identifier (name) of the property to be removed. |
Moving a Code in the Subsumption Hierarchy
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.
As with all update operations, moveCode has a separate, optional ballotStatus node. The moveCode attributes specify the operation to be performed:
| 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. |
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.
Retiring a Concept Code
While a concept code may never be reused within a code system, it may be 'retired' from active use.
As with all operations, retireCode may be accompanied by an optional ballotStatus. The attributes of retireCode determine what actually happens:
| conceptCode | The code of the concept to be retired |
|---|---|
| conceptName | A valid designation for the concept to be retired. Required. |
| 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>> |
Removing Existing Concept Relationships
It is also possible to undo relationships that have previously been asserted using the addConceptRelationship node.
Like all operations, removeConceptRelationship can have a ballotStatus entry that overrides the outside status. removeConceptRelationship has the following 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. |
Value Set Revisions
A value set represents a list of concept codes from a single code system. Value sets are used to identify the list of possible values for a coded attribute based on the HL7 RIM.
Value sets can be constructed in one of three ways:
- A value set can represent all of the concept codes in a given code system
- A value set can represent selected codes from a code system. Codes may be selected by:
- Identifying individual concept codes
- Identifying a concept code and a relationship (e.g. hasSubtype, hasPart) and stating one of:
- The concept code and all related concepts are included in the set
- All related concepts except the named concept are included in the set
- All leaf nodes of the specified relationship are included in the set
- A value set can include codes from other value sets.
Note that the third form of construction actually makes it possible to mix concept codes from more than one code system in a single value set. This form should only be used, however, when the semantic space of the two value sets are disjoint - meaning that there is no possibility that the same concept could be represented using different codes from different systems.
When one value set is included in another set, sometimes it is useful to identify a concept code that represents the included value set as a whole (e.g. in the nullFlavor value set, one of the choices is “NoInformation (NI)”, which can be used instead of more specific flavors such as “masked (MSK)”, “not applicable (NA)”, etc.). When this is the case, the “whole” concept code can be identified by associating it with a value set as the “head code”. When this value set is included in a second value set, the include specifies whether the “head code” is a selectable value or not. Refer to the examples on the following pages for further clarification.
The value set revision process can be used to create new value sets as well as to modify the contents of existing sets.
Creating a New Value Set
ballotStatus is the first element defined when creating a value set. As described above, it is optional except in the case when the vocabularyRevision.documentStatus is Final, in which case all revisions have to be associated with a non- Proposed status.
The valueSetMetaData element provides a place to document a description of the changes that this value set creation entails. (The text may include xhtml markup, and is placed within the "valueSetMetaData" element.) further, the element has a single attribute.
| isImmutable | If set, the value set definition will be declared immutable. |
|---|
The description element is technically optional but virtually required by HL7 style and ballot guides. When present, it provides a description of the use and purpose of the value set.
| setName | The unique name of the value set |
|---|---|
| codeSystemName | The mnemonic for the code system associated with the value set (if any) |
| allCodes | If codeSystemName is supplied, this flag determines whether all of the codes in the code system are included in the value set or just selected codes. |
| headCode | It codeSystemName is supplied, this can be the concept code of the “head code” – the code that represents the entire value set. |
| headCodePrintName | A valid designation for the headCode. Optional, but validated if supplied. |
| asVocabularyDomain | <<Editor unsure of meaning. Does it mean "If true means that a concept domain should also be created."?>> |
The fragment in the example above creates a value set called “OrderableBeers” and assigns all of the codes from the BEERS code system to the set. It then creates a second value set called OrderableAles that is also drawn from the BEERS code system and assigns code 1001 (ALES) as the head code for the value set.
The underValueSet element allows the newly created value set to be added as nested element in an already existing value set.
| setName | The name of an existing value set to add this new value set under |
|---|---|
| addAsType | One of abstract or specializable. Abstract means that the head code (if any) of the new value set is not to be considered part of setName. Specializable means that the head code (if any) is to be included in setName. |
Adding Concept Codes to a Value Set
A list of concept codes may be added to a newly created value set as well as a previously existing value set.
The first element, ballotStatus, is optional. If supplied, it overrides any other applicable ballot status settings. Each codeAddition entry adds a concept code to the current value set. The order of the codeAddition entries is not important. A value set must have had a code system assigned to it in order to add individual concept codes.
| conceptCode | The concept code to be added to the value set. |
|---|---|
| conceptName | A valid designation for the concept code. Optional, but validated if supplied |
| relationship | An optional relationship code. If present, it indicates that codes that are “children” of conceptCode are to be included in the value set as well. If omitted, only conceptCode itself is included. Note that hasSubtype is the official subsumption relationship. |
| relInclusion | Indicates which of the related codes are to be included. Applies only if relationship is supplied. (See table below) |
| relInclusion | Meaning |
|---|---|
| inclusive | conceptCode and all of its direct and indirect “children” are included in the value set. |
| exclusive | All of the direct and indirect “children” of conceptCode are included, but not conceptCode itself. |
| leafOnly | Only the “leaf” descendants of conceptCode are to be included in the value set. |
The above example adds concept codes 1002, 1003 and 1004 to the OrderableAles value set.
The above example adds all of the children of the “ALES” node to the “SpecificAles” value set. Note that this is subtly different than the preceding example. In the first example, codes 1001, 1002, 1003 and 1004 are the only members of the OrderableAles value set, even if new types of ales are added to the code system. The second example creates exactly the same set to start with, but would automatically acquire new members were new children added to the 1001 (ALES) node.
Adding References to other Value Sets
As described earlier, value sets can also reference other value sets. One way to establish this sort of reference was the underValueSet element of createValueSet. This mechanism, which was described previously, created a reference from an existing value set to a newly created set. A second way to create value set references is through the addValueSetReference element. addValueSetReference elements may occur under both the value set creation (createValueSet) and value set modification (selectValueSet) nodes.
Each addValueSetReference entry can include an optional ballot status which, if present, overrides any outer ballot status entry. addValueSetReference consists of one or more listEntry, each of which names a value set to be added to the current value set being created or modified.
| setName | The name of the value set to reference. |
|---|---|
| setType | One of abstract or specializable. Abstract means that the head code of setName (if any) is not included as part of the value set being defined. Specializable means that the head code (if any) is to be included. |
The above example creates a value set named “OrderableBeers”, which is composed of two other value sets – “SpecificAles” and “SpecificStouts”. The head code for SpecificAles is not included in the value set, while the head code for SpecificStouts is.
Adding the Value Set to an Existing Concept Domain
<<Editor: This section represents a limitation in the Vocabulary Maintenance Language. With this section, it is possible to add new Context Bindings, but there is NO capability to delete or edit such bindings once they have been added.>> This needs to be added to the VML.
The newly created or previously selected value set can be added to one or more already existing concept domains. When adding the value set it is also possible to specify in which context the value set is applicable.
Like all other update elements, addToVocabularyDomain can specify a ballot status. If supplied, this ballot status overrides any previous applicable status.
| vocabularyDomain | The name of the concept domain to add the value set to |
|---|---|
| context | An optional context identifier (commonly the code of a binding realm such as UV for Universal, or CA for Canada). If present, it indicates that the value set only applies in that given domain.
<<Editor: This definition seems incomplete. If the context is not specified, the binding will be treated as incomplete or some such. Also, in the data base, there should be multiple valid contexts, or else one binding per context, which means the field cannot be optional.>> |
The above example adds the “SpecificAles” value set to the “OrderableAles” concept domain. Note that the concept domain has to exist in order for this operation to succeed.
Modifying Existing Value Sets
Previously defined value sets may be updated as well. The value set to be revised is identified by the selectValueSet node. All of the modifications are specified within the selectValueSet node.
The first element of a selectValueSet node can be a ballotStatus. If specified, this status applies to all operations within the selectValueSet element unless it is specifically overridden.
The valueSetMetaData element provides a place to document a description of the changes that modifying this value set creation entails. (The text may include xhtml markup, and is placed within the "valueSetMetaData" element.) further, the element has a single attribute to designate the value set as immutable.
| isImmutable | If set, the value set definition will be declared immutable. |
|---|
selectValueSet has one attribute:
| setName | The name of the value set to be modified. |
|---|
Concept codes or references to other value sets may be added to the selected set, and the set may be added to one or more concept domains. These operations (shown with a gray background in the figure two before here) are all described under the section on creating value sets. In addition to the creation operations, the selected value set can be modified, deleted, and have references to codes or other value sets removed.
Deleting a Value Set
deleteValueSet has one optional element, the ballot status, which can be used to override an outer status. It has a single attribute:
| andVocabularyDomain | If true, indicates that if there any domains to which this value set is bound, they should be deleted also. |
|---|
Modifying the Definition of a Value Set
The name, code system, head code, allCodes setting and description of a value set can all be changed.
modifyValueSet has three sub-elements that are all optional - the ballotStatus, an oldDescription and a newDescription. The ballot status needs be present only if it overrides an outer ballot status setting. If present, oldDescription contains the existing description for the value set if any. If present, it will be validated by comparing it with the existing database. If newDescription is present, the description of the value set will be updated accordingly. modifyValueSet also has a number of attributes, which are listed below.
| newName | If present, the name of the selected value set will be changed to newName. |
|---|---|
| codeSystem | If present, the code system associated with the value set will be updated to this value. |
| allCodes | If present, the allCodes setting will be changed to reflect this value |
| headCode | If present, the head code will be changed to this value (or deleted if an empty string is supplied |
| headCodeName | A designation for headCode. Optional but if supplied it will be validated against headCode. |
The above example:
- Changes the allCodes setting on “OrderableBeers” to false
- Removes any code system that may currently be specified
- Updates or adds a description.
Removing Concept Codes from a Value Set
Concept codes that are currently associated with a value set can be removed.
removeCodesFromValueSet contains an optional ballot status followed by a list of codes to be removed. Each codeToRemove element has two attributes:
| conceptCode | The coded concept to remove from the value set. If the coded concept referenced other concepts via a relationship, those references will be removed as well. |
|---|---|
| conceptName | A valid designation for conceptCode. Validated if supplied. |
The above example removes concept code 1003 (BITTER ALE) from the “OrderableAles” value set.
Removing References to Other Value Sets
removeValueSetReferences removes one or more references to other value sets from the selected set. As with any modification operation, it has an optional ballot status that can be used to specifically state the status for this item. It then contains a list of removeReferenceTo elements, each of which identifies a value set reference to be removed. The attribute for removeReferenceTo is:
| valueSet | The name of the value set to be removed. |
|---|
Concept Domain Revision
A concept domain represents an abstract conceptual space that can be associated with RIM-derived coded attributes. A concept domain can be represented by one or more value sets, where each associated value set applies in a given context. Further, sub-sets of concept domains may, themselves, be represented as concept domains in a parent-child semantic hierarchy. The set of operations that can be made on concept domains includes: create, define (or redefine), rename, move (in the hierarchy) and delete, as indicated below:
Creating Concept Domains
The vast majority of the concept domains will be created during the RIM modeling process. The following operation can be used in cases where the domain doesn’t already exist in the RIM model.
The creation of a new domain needs to be voted upon, therefore createVocabularyDomain has an optional ballotStatus element. The description is technically optional, but is virtually required by HL7's style and balloting guides. It provides a description of the concept domain. createVocabularyDomain has the following attributes:
| vocabularyDomain | The name of the new concept domain to be created |
|---|---|
| restrictsDomain | The name of the parent concept domain (optional). |
The example above creates two concept domains – OrderableBeers and OrderableAles. OrderableAles is defined as a proper subset (restriction or constraint) on OrderableBeers.
Define or Redefine Concept Domain
A new or revised definition can be assigned to a concept domain with the defineVocabularyDomain element.
As with all updates, defineVocabularyDomain can have its own ballotStatus if needed to reflect special cases. It has a newDescription element that contains the revised description or can be empty if the description is to be completely removed. defineVocabularyDomain has a single attribute:
| vocabularyDomain | The name of the concept domain to be (re)defined. |
|---|
Rename Concept Domain
A new name can be assigned to a concept domain with the renameVocabularyDomain element.
As with all updates, renameVocabularyDomain can have its own ballotStatus if needed to reflect special cases. renameVocaabularyDomain has two attributes:
| vocabularyDomain | The current name of the concept domain to be (re)defined. |
|---|---|
| newDomainName | The new name of the concept domain. |
Move Concept Domain
A concept domain can be moved within the domain hierarchy – made a child of another domain, made a child of a different domain than previously, or removed from under its parent -- using the moveVocabularyDomain element.
As with all updates, moveVocabularyDomain can have its own ballotStatus if needed to reflect special cases. moveVocaabularyDomain has three attributes:
| vocabularyDomain | The name of the concept domain being moved. |
|---|---|
| fromDomain | The current direct parent of the concept domain, if any. This attribute should be omitted if the concept domain doesn’t currently occur under any other node. |
| toDomain | The new parent of the concept domain. If omitted, the concept domain no longer has a parent in the domain hierarchy. |
Delete Concept Domain
A concept domain can be deleted from the set of HL7 domains using the moveVocabularyDomain element.
As with all updates, moveVocabularyDomain can have its own ballotStatus if needed to reflect special cases. moveVocaabularyDomain has one attributes:
| vocabularyDomain | The name of the concept domain to be deleted. |
|---|
- Capability that is listed as Not exposed in application are functions that are not (as of this writing) supported by the Harmonization Tooling application.
- Capability that is listed as Not fully exposed in application represents a set of capabilities, some, but not all of which is implemented in the Harmonization Tooling application.
- Code System capability that is listed as Exposed under VS in application are functions that cannot be invoked directly, but that are present in processing value set changes on Value Sets whose Code System is established by a previous binding
- The term Concept Domain was formally adopted by the HL7 Vocabulary Technical Committee as the name for an abstract conceptual space that may be represented by (bound to) a set of concepts found in one or more specific code systems. Previous to this adoption, the preferred name for the same abstract conceptual space was Vocabulary Domain. In editing this document, the term "vocabulary domain" has been replaced with "concept domain", except where the term is part of the XML schema. In order to avoid "breaking" software tools that were built to the previous version of the schema, the XML attribute and element names retain the phrase "vocabularyDomain".
Appendices
A – Beer Classification Example
B – Beer Classification Example in XML
C – Complete Listing of Examples Used in Document
D – VocabularyRevision Schema
Harmonization Tool Documentation
work in progress
