Vocabulary Maintenance Language (Value Set Revision)
| Introduction | Proposal | Code System | Value Set | Domain | Properties | Appendices |
CreateValSet ···
AddCodesToValSet ·
AddRefsToOtherValSet ·
BindValSetToDomain
ModifyValSet ···
DeleteValSet ·
RedefineValSet ·
RemoveCodesFromValSet ·
RemoveRefsToOtherValSet
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. |
|---|
- 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".
