VocMnt-ValueSetRev/Create

Creating a New Value Set

Element createValueSet

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

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.

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.

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.

Adding the Value Set to an Existing Concept Domain

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