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:

1. A value set can represent all of the concept codes in a given code system
2. A value set can represent selected codes from a code system. Codes may be selected by:
   1. Identifying individual concept codes
   2. Identifying a concept code and a relationship (e.g. hasSubtype, hasPart) and stating one of:
      1. The concept code and all related concepts are included in the set
      2. All related concepts except the named concept are included in the set
      3. All leaf nodes of the specified relationship are included in the set
3. 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.

Element valueSetRevision

Jump to top of page

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.

Attributes of createValueSet

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."?>>

Example XML for createValueSet

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.

Attributes of underValueSet

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.

Jump to top of page

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.

Element addCodesToValueSet

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.

Attributes of codeAddition

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 Values

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.

Example XML for addCodeToValueSet

The above example adds concept codes 1002, 1003 and 1004 to the OrderableAles value set.

Example XML for valueSetRevision with a specified relationship

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.

Jump to top of page

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.

Element addValueSetReference

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.

Attributes of listEntry

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.

Example XML for addValueSetReferences

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.

Jump to top of page

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.

Element addToVocabularyDomain

Like all other update elements, addToVocabularyDomain can specify a ballot status. If supplied, this ballot status overrides any previous applicable status.

Attributes of addToVocabularyDomain

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.>>

Example XML for addToVocabularyDomain

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.

Jump to top of page

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:

Attribute of selectValueSet

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.

Jump to top of page

Deleting a Value Set

Element deleteValueSet

deleteValueSet has one optional element, the ballot status, which can be used to override an outer status. It has a single attribute:

Attribute of selectValueSet

andVocabularyDomain	If true, indicates that if there any domains to which this value set is bound, they should be deleted also.

Example XML for deleteValueSet

Jump to top of page

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.

Element modifyValueSet

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.

Attributes of modifyValueSet

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.

Example XML for modifyValueSet

The above example:

1. Changes the allCodes setting on “OrderableBeers” to false
2. Removes any code system that may currently be specified
3. Updates or adds a description.

Jump to top of page

Removing Concept Codes from a Value Set

Concept codes that are currently associated with a value set can be removed.

Element removeCodesFromValueSet

removeCodesFromValueSet contains an optional ballot status followed by a list of codes to be removed. Each codeToRemove element has two attributes:

Attributes of codeToRemove

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.

Example XML for removeCodesFromValueSet

The above example removes concept code 1003 (BITTER ALE) from the “OrderableAles” value set.

Jump to top of page

Removing References to Other Value Sets

Element removeValueSetReferences

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:

Attributes of removeReferenceTo

valueSet	The name of the value set to be removed.

Jump to top of page

---

Not exposed in application

Capability that is listed as Not exposed in application are functions that are not (as of this writing) supported by the Harmonization Tooling application.

Not fully exposed in 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.

Exposed under VS in 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

Concept Domain

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".