|
|
Line 21: |
Line 21: |
| [[Image:VocMnt440.gif|thumb|center|384px|Element '''valueSetRevision ''']] | | [[Image:VocMnt440.gif|thumb|center|384px|Element '''valueSetRevision ''']] |
| | | |
− | ===Creating a New Value Set===
| + | {{:VocMnt-ValueSetRev/Create}} |
− | | |
− | [[Image:VocMnt450.gif|thumb|center|384px|Element '''createValueSet''']]
| |
− | | |
− | [[#Ballot_Status|'''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.
| |
− | | |
− | [[Image:VocMnt460.gif|thumb|center|512px|Attributes of '''createValueSet ''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left" | |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|setName
| |
− | |The unique name of the value set
| |
− | |-
| |
− | !valign="top"|codeSystemName
| |
− | |The mnemonic for the code system associated with the value set (if any)
| |
− | |-
| |
− | !valign="top"|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.
| |
− | |-
| |
− | !valign="top"|headCode
| |
− | |It codeSystemName is supplied, this can be the concept code of the “head code” – the code that represents the entire value set.
| |
− | |-
| |
− | !valign="top"|headCodePrintName
| |
− | |A valid designation for the '''headCode'''. Optional, but validated if supplied.
| |
− | |-
| |
− | !valign="top"|asVocabularyDomain
| |
− | |'''<<Editor unsure of meaning. Does it mean ''"If true means that a concept domain should also be created."''?>>'''
| |
− | |}
| |
− |
| |
− | [[Image:VocMnt471.gif|thumb|center|640px|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.
| |
− | | |
− | [[Image:VocMnt480.gif|thumb|center|512px|Attributes of '''underValueSet ''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left" | |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|setName
| |
− | |The name of an existing value set to add this new value set under
| |
− | |-
| |
− | !valign="top"|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.
| |
− | | |
− | [[Image:VocMnt490.gif|thumb|center|384px|Element '''addCodesToValueSet ''']]
| |
− | | |
− | The first element, [[#Ballot_Status|'''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.
| |
− | | |
− | [[Image:VocMnt500.gif|thumb|center|512px|Attributes of '''codeAddition''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|conceptCode
| |
− | |The concept code to be added to the value set.
| |
− | |-
| |
− | !valign="top"|conceptName
| |
− | |A valid designation for the concept code. Optional, but validated if supplied
| |
− | |-
| |
− | !valign="top"|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.
| |
− | |-
| |
− | !valign="top"|relInclusion
| |
− | |Indicates which of the related codes are to be included. Applies only if relationship is supplied. '''''(See table below)'''''
| |
− | |}
| |
− | :
| |
− | :
| |
− | {| border="1" cellpadding="5" cellspacing="0"
| |
− | |+'''<u>relInclusion</u> Values'''
| |
− | !width="15%"|relInclusion
| |
− | !Meaning
| |
− | |-
| |
− | |valign="top"|inclusive
| |
− | |'''conceptCode''' and all of its direct and indirect “children” are included in the value set.
| |
− | |-
| |
− | |valign="top"|exclusive
| |
− | |All of the direct and indirect “children” of '''conceptCode''' are included, but not '''conceptCode''' itself.
| |
− | |-
| |
− | |valign="top"|leafOnly
| |
− | |Only the “leaf” descendants of '''conceptCode''' are to be included in the value set.
| |
− | |}
| |
− | :
| |
− | :
| |
− | [[Image:VocMnt511.gif|thumb|center|640px|Example XML for '''addCodeToValueSet ''']]
| |
− | | |
− | The above example adds concept codes 1002, 1003 and 1004 to the OrderableAles value set.
| |
− | | |
− | [[Image:VocMnt521.gif|thumb|center|640px|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.
| |
− | | |
− | [[Image:VocMnt530.gif|thumb|center|384px|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.
| |
− | | |
− | [[Image:VocMnt540.gif|thumb|center|512px|Attributes of '''listEntry ''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|setName
| |
− | |The name of the value set to reference.
| |
− | |-
| |
− | !valign="top"|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.
| |
− | |}
| |
− | | |
− | [[Image:VocMnt551.gif|thumb|center|640px|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.
| |
− | | |
− | [[Image:VocMnt560.gif|thumb|center|384px|Element '''addToVocabularyDomain''']]
| |
− | | |
− | Like all other update elements, '''addToVocabularyDomain''' can specify a ballot status. If supplied, this ballot status overrides any previous applicable status.
| |
− | | |
− | [[Image:VocMnt570.gif|thumb|center|512px|Attributes of '''addToVocabularyDomain''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|vocabularyDomain
| |
− | |The name of the concept domain to add the value set to
| |
− | |-
| |
− | !valign="top"|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.>>'''
| |
− | |}
| |
− | | |
− | [[Image:VocMnt581.gif|thumb|center|640px|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.
| |
− | | |
− | ===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.
| |
− | | |
− | [[Image:VocMnt590.gif|thumb|center|384px|Element '''selectValueSet''']]
| |
− | | |
− | The first element of a '''selectValueSet''' node can be a [[#Ballot_Status|'''ballotStatus''']]. If specified, this status applies to all operations within the '''selectValueSet''' element unless it is specifically overridden. '''selectValueSet''' has one attribute:
| |
− | | |
− | [[Image:VocMnt600.gif|thumb|center|512px|Attribute of '''selectValueSet ''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|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====
| |
− | | |
− | [[Image:VocMnt610.gif|thumb|center|384px|Element '''deleteValueSet''']]
| |
− |
| |
− | '''deleteValueSet''' has one optional element, the ballot status, which can be used to override an outer status. It has a single attribute:
| |
− | | |
− | [[Image:VocMnt615.gif|thumb|center|512px|Attribute of '''selectValueSet''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|andVocabularyDomain
| |
− | |If '''''true''''', indicates that if there any domains to which this value set is bound, they should be deleted also.
| |
− | |}
| |
− | | |
− | [[Image:VocMnt621.gif|thumb|center|640px|Example XML for '''deleteValueSet ''']]
| |
− | | |
− | ====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.
| |
− | | |
− | [[Image:VocMnt630.gif|thumb|center|384px|Element '''modifyValueSet ''']]
| |
− | | |
− | '''modifyValueSet''' has three sub-elements that are all optional - the [[#Ballot_Status|'''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.
| |
− | | |
− | [[Image:VocMnt640.gif|thumb|center|512px|Attributes of '''modifyValueSet''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|newName
| |
− | |If present, the name of the selected value set will be changed to newName.
| |
− | |-
| |
− | !valign="top"|codeSystem
| |
− | |If present, the code system associated with the value set will be updated to this value.
| |
− | |-
| |
− | !valign="top"|allCodes
| |
− | |If present, the '''allCodes''' setting will be changed to reflect this value
| |
− | |-
| |
− | !valign="top"|headCode
| |
− | |If present, the head code will be changed to this value (or deleted if an empty string is supplied
| |
− | |-
| |
− | !valign="top"|headCodeName
| |
− | |A designation for '''headCode'''. Optional but if supplied it will be validated against '''headCode'''.
| |
− | |}
| |
− | | |
− | [[Image:VocMnt651.gif|thumb|center|640px|Example XML for '''modifyValueSet ''']]
| |
− | | |
− | 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.
| |
− | | |
− | [[Image:VocMnt660.gif|thumb|center|384px|Element '''removeCodesFromValueSet''']]
| |
− | | |
− | '''removeCodesFromValueSet''' contains an optional ballot status followed by a list of codes to be removed. Each c'''odeToRemove''' element has two attributes:
| |
− | | |
− | [[Image:VocMnt670.gif|thumb|center|512px|Attributes of '''codeToRemove''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|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.
| |
− | |-
| |
− | !valign="top"|conceptName
| |
− | |A valid designation for '''conceptCode'''. Validated if supplied.
| |
− | |}
| |
− | | |
− | [[Image:VocMnt681.gif|thumb|center|640px|Example XML for '''removeCodesFromValueSet''']]
| |
− | | |
− | The above example removes concept code 1003 (BITTER ALE) from the “OrderableAles” value set.
| |
− | | |
− | ====Removing References to Other Value Sets====
| |
− | | |
− | [[Image:VocMnt690.gif|thumb|center|384px|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:
| |
− | | |
− | [[Image:VocMnt700.gif|thumb|center|512px|Attributes of '''removeReferenceTo''']]
| |
− | | |
− | {| class="wikitable" style="text-align:left"
| |
− | !width="15%"|
| |
− | !
| |
− | |-
| |
− | !valign="top"|valueSet
| |
− | |The name of the value set to be removed.
| |
− | |}
| |
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 vocabulary 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.
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.
|