NIH | National Cancer Institute | NCI Wiki  

Contents of this Page

Helpful Hint

To edit content or add comments to this wiki, you need to be logged in using your wiki account. If you do not have a wiki account, please sign up for an account.

Value Domain Best Practices Presentation

Presentation on enumerated value domains given at the January 2010 VCDE bi-weekly.

Best Practices for Enumerated Value Domains for UML v2 -VCDE.ppt

Value Domain Decision Tree - DRAFT

Click to view the draft of a decision tree for how to create value domains

Identified Value Domain Issues

Define enumerated by reference and difference from enumerated Value Domain
Not currently covered in the Curating Metadata from UML Models courses. Need to tell when it is appropriate to use a reference document (list of values maintained somewhere else). SIW can handle this when the reference is a top level concept in EVS.

Indications for both types of Value Domains

How does SIW handle enumerated by reference?
Enumerated by reference are not currently handled by SIW. Only the VD attributes (NOT the reference document URL itself) are created/added in the UML Class diagram that is run through SIW. To use/create an enumerated by reference in a UML Model, the model owner can:

  1. Use the Value Domain concept code tag (make reference to the XMI wiki page) in the UML Class Diagram, on the stereotyped class. This cannot be put in SIW, it must be in the Model itself (in EA). Only one Parent Concept per referenced value domain is permitted. This tag is equal to selecting a "Parent Concept" when editing permissible values.
  2. Map to an existing enumerated by reference Value Domain
  3. Map to an existing Value Domain that is then versioned by manual curation to include a referenced list of values
  4. Map EVS concepts to a new VD (from the UML Model); then the referenced list of values can be hand-curated post load of the model

How does EA handle enumerated by reference VDs?
Only the VD attributes (NOT values themselves) are created/added in EA for an enumerated by reference. The referenced values must be hand-curated.

Are there manual steps involved that needs to be handed off to the curation team?

How are enumerated VDs created now in caDSR?
Two options:

  1. Hand curate the VD with a list of enumerated values. Instructions are in the 1060 Course Series (Curating Metadata from Forms)
  2. Create a stereo-typed class in your UML Model of type "caDSR Value Domain"; instructions are in the 1070 Course Series (Curating Metadata from UML Models).

How does EA handle it?
The stereo-typed class "caDSR Value Domain" is created in EA by the model owner. Permissible Values are added as attributes (with tags) to this class. Instructions are in the 1070 Course Series.

How does SIW handle it?
The SIW will load the special, stereotyped classes from the EA model.

How does a person search for a list of values to reuse?

  1. Search the caDSR for existing Data Elements (using the CDE Browser, or Curation Tool)
  2. Search the caDSR for existing Value Domains (using the CDE Browser, or Curation Tool)
  3. Search the caDSR for existing Class Attributes (using the UML Model Browser)
  4. Search EVS (thru BioPortal or one of the caDSR Tools) for a primary concept that has a list of sub-concepts that match your value list

Do all permissible values need to be annotated?
No. There are some cases of internal-use values (e.g. a list of room numbers for hospital departments, or a list of doctor's names that are institution specific) that would not have EVS concept annotations.

How about the case of institution-specific values?
See question above.

Silver Compatibility Criteria and Enumerated Value Domains



Silver level requirement

Tool Capable

Human Capable


All Data Elements have names, definitions, datatypes, and permissible values that have unambiguous meanings.





The concept terms assigned to the Permissible Values (in the Value Domain) of each CDE must be from a controlled vocabulary approved by VCDE before they can be assigned a status of "released" in the caDSR.





If permissible values are specified, each permissible value must have a value name that is listed in a publicly available repository. Repositories can include the CDE itself (i.e., caDSR) or EVS.





If permissible values are specified, each permissible value must have a value meaning from a publicly available repository. Repositories can include the CDE itself (i.e., caDSR) or EVS.





If permissible values are specified, each permissible value should have a concept code from a VCDE approved controlled vocabulary assigned to the value meaning.  Institution-specific values are exempt.





If permissible values are specified, each permissible value should have a definition for the value meaning.





Permissible Values should be annotated within the UML model according to the guidelines specified in the caCORE SDK User's Guide.




Parent Concepts as Tagged Values in EA

Notes on how the "parent concept" entered as tagged values around "ValueDomainConceptCode" in EA are stored and used in caDSR.

The intent/purpose of the value domain concept code depends on the Value Domain type - Enumerated or Non-enumerated.

For Enumerated, you can have one or more, the additional concepts are entered as 'qualifier' concepts (designed as an efficiency thing... the name "ValueDomainParentConcept" would have been better and then just allowing multiple values if its "E" and not if its "N" probably would have been clearer).

From the "XMI Reference" wiki page: "Use to denote a concept mapped at the Value Domain level. The meaning of this concept association depends on whether the Value Domain is a Non-enumerated "N", or Enumerated, "E", VD. For "N" VDs, Non-enumerated VD, the presence of one ConcpetCode is permitted at the Value Domain level and represents a 'Referenced Enumeration', or "Enumerated by Reference", meaning that the of value list is not managed within the registry, but a parent concept exists in EVS by which a program implementing the value domain could constrain data collection. The resolution of this type of reference can be performed using the current EVS APIs, but takes knowledge of the terminology domain model. A high level service to return all the subconcepts of a "Parent Concept" is planned for a future EVS release. For an "E", Enumerated VD, one or more "Parent Concepts" can be created at the VD level that act to restrict the list of permissible values for values being managed within caDSR for the VD. To support this use case, the "qualifier concept code" tagged values are used to name more than one "Parent Concept". See SIW and UML Loader technical guide for details. Tagged Value on the class with stereotype = 'CADSR Value Domain'."



  • No labels