Skip Navigation Bar

VSAC Support Center

VSAC Authoring Best Practices


The Value Set Authority Center (VSAC) serves as the authority and central repository for the Centers for Medicare & Medicaid (CMS) Electronic Clinical Quality Measure (eCQM) Value Sets, as well as value sets for use in other programs and within a wide range of data models. The VSAC provides search, retrieval and download capabilities through a Web interface and through an API. A major function of the VSAC is the VSAC Authoring Tool for users to create value sets, as well as a VSAC Collaboration Tool for authors to collaborate on their VSAC content.

These guidelines are intended for value set authors. The guidelines provide an overview and specific guidance on the best practices for authoring value sets for clinical quality measures and other healthcare applications. The main focus of these guidelines is to describe criteria that define a high quality value set.

A value set contains specific codes derived from a single code system or vocabulary, for example, RxNorm, ICD-10-CM, ICD-9-CM, SNOMED CT, LOINC, and CPT, although value sets can be grouped to combine code systems. In the CMS eCQMs program, value set codes populate an instance of a Quality Data Model (QDM) category of information in an electronic health record. The Health Information Technology Standards Committee (HITSC) Vocabulary Task Force and Clinical Quality Workgroups identified the primary code systems for use with each QDM category of information. The Clinical Quality community continues to work on these recommendations to assure they are more comprehensive and not too restrictive.

  • Extensional: A set of concept codes and descriptors, in the form of an enumerated list, selected to serve a specific clinical purpose. A simple enumeration of concepts is not always an ideal approach to define a value set, as a comprehensive approach to clinical quality measure development dictates examination of complete code hierarchies in a code system to define the levels of concept inclusion (see Intensional Value Sets below). An extensional value set contains codes from only one code system.

    Extensional Value Set

  • Grouping: A list of several value sets that share a common purpose and similar clinical concepts. For CMS eCQMs, specifically, members of a grouping value set must have the same Quality Data Model Category, but the value set members of the grouping do not need to share the same code system. For example, the "Wound Care" Grouping used in measure CMS188v6 uses three value sets, ICD-9-CM, ICD-10-PCS, and SNOMED CT, all of which relate to wound care.

    Grouping Value Set

  • Intensional: A list of codes based on a logical statement that often has an algorithmic basis for selection of concepts. For example, "include all concepts that are children of a parent concept" in a hierarchical code system. Intensional value set functionality is under development and not yet available in VSAC.

Standardization of value sets is imperative, as it enables value set comparison across data sets. Adherence to these quality criteria facilitates reuse of well-defined value sets to advance clinical research studies and interoperability of health informatics analysis systems. Value set authors should clearly understand major principles that define high quality value sets:

  • Clinical Validity: Value set authors should assure that all included codes correspond to the intent and purpose from a clinical perspective. For example, a code defining breast malignancies might be considered clinically irrelevant in a value set that defines eye disease. However, there might be more subtle nuances in clinical meaning one may need to consider.
  • Metadata Completeness: Authors must provide correct and complete metadata and add any missing metadata as defined by the data model they use or program under which the authors work. Value sets defined by different clinical data models will have specific sets of metadata. The VSAC Authoring Tool indicates which metadata elements are mandatory. Authors should not populate free-text fields with meaningless information, as this will hinder the collaborative process of eliminating value set redundancy and harmonization efforts of the value set user community.
  • Non-redundancy: Ideally, a given data element should be presented by one and only one value set for a given code system. Multiple value sets with the same codes should be eliminated to facilitate maintenance and prevent inconsistency over time. For example, duplicate value sets should be avoided, and value sets that share a majority of codes should be considered for merging or revision to assure the value sets are as complete as possible.
  • All Value Set Codes Are Valid in the Code System: The authors should consider only currently valid codes for inclusion into a value set. This assures proper maintenance of the value sets. In some specific cases the author will need to specify a specific version of the code system and would thus create a static snapshot of the code system. Such cases should generally be an exception of the rule, limited whenever possible, and properly described in the Purpose statements.
  • Descriptors Match Code System Descriptors: Authors should make sure any descriptors they add manually to value sets match the descriptors in the code system to which the codes belong. The VSAC Authoring Tool provides a descriptor match check as a built in function. The VSAC Authoring Tool performs this validation during batch import of codes into a value set, and during manual insertions of codes and descriptors.
  • Code List Completeness: A value set should contain all the relevant codes for a particular data element. The coverage of codes should be correct. Authors should make sure the lists are lean and they should scrutinize large value sets. You should devise working rules and quality assessment tests to determine whether or not a concept or code is a proper member of a value set. Authors should describe such rules and tests in the required value set Purpose statement.
  • Logical Correctness: A value set should contain only the relevant codes for a particular data element and the codes contained in the value set should strictly align with the described Purpose.
  • Proper Terminological Hierarchies (terminological correctness): Only root codes and their descendants should be present in the value set. Presence of codes rooted at a different concept normally indicates incorrect choice of codes. In complex cases, value set authors should consult terminology experts.
  • Concept Property Similarity: Value set member concepts should not vary in respect to their properties and attributes, such as semantic type, term type, etc. For example, a value set intended for prescribable drugs should contain only drugs with the property, "Prescribable." This is applicable for concepts that have such properties. The properties should be more similar than dissimilar. For complex cases, value set authors should seek guidance on the matter from terminology experts.
  • Code System Alignment to Standards: Value set authors should base their value set on the code system recommended by the standards depending on the purpose of their value set and the data model (such as the National Quality Forum Quality Data Model) to which the value set authors may be adhering. Please refer to the Quality Data Model Categories with Office of the National Coordinator (ONC) Health Information Technology (HIT) Standards Committee Recommended Vocabularies, in the most recent version of the CMS Measures Management System Blueprint.

The name of a value set is a crucially important and descriptive metadata element. Value set authors should adhere to specific naming guidelines to assure value sets can be found manually and through automated processing, to encourage reuse of the value sets and to discourage their redundancy. The following guidelines will help you create concise, descriptive value set names that capture the purpose of each value set.

Do's:

  • Name the value set exactly for what it is, not what you wanted it to be. Avoid including descriptions of the content that was intended but not achieved. Correct the name accordingly if during the course of the work you discovered you were not able to align the value set content with the initial name given to the value set. For example, if you initially named the value set "Oral Anticoagulants" when the intent was to capture only oral anticoagulants for chronic atrial fibrillation, change the name to "Oral Anticoagulants for Chronic Atrial Fibrillation" to align it with the intended purpose.
  • Write the value set name to convey the specific distinguishing characteristics of the member concepts. See the name in the previous bullet for a good example.
  • Use sufficiently descriptive names. Using the example from the first bullet, the value set name "Oral Anticoagulants" is not sufficiently descriptive because it does not describe the scope of the value set. The value set name "Oral Anticoagulants for Chronic Atrial Fibrillation" is a better name because it effectively describes the scope of the value set.
  • Separate multi-word terms by spaces and not by any other characters.
  • Capitalize first letters of all words, except prepositions, as in a title.
  • Make unique value set names. Due to the uniqueness of the value set purpose and content, name redundancy ought to be a very rare occurrence.
  • Limit the value set name to as few words as possible, and no more than 128 characters.

Don'ts:

  • The following characters are technically prohibited and you will get a system warning if they are used: + * ? : - | ! " %
  • Avoid abbreviations, unless they are widely accepted in the medical literature.
  • Do not include the name of the steward responsible for the value set. The steward name is separate metadata bound to the value set and captured in the VSAC database.
  • Avoid including the name of the Quality Data Model data element to which the value set will be linked if the value set is to be referenced as part of a Clinical Quality Measure.
  • Do not include the name of the Program that sponsors the system in which the value set is used, unless it describes a primary distinguishing characteristic of the value set.
  • Do not include the name of the code system used to obtain the concepts, unless it describes a primary distinguishing characteristic of the value set. For example, extensional value sets that belong to a grouping value set might be an appropriate case in which you would include the code system name.
  • Do not include the concept category that characterizes the context of use, unless it describes a primary distinguishing characteristic of the value set requirements. For example, only include the word "Procedure" when the context of the main focus is ambiguous.
  • Avoid using the word "Other" as an alternative to another value set. Each value set name must be understandable independent of any other value set.
  • Do not include "CamelCase" or other composite and delimited words or phrases.
  • Avoid using code descriptors within the value set name.
  • Do not use names of measure types for which the value set is intended. For example, do not include "hospital measure," "patient measure," etc. Include this information in the value set Purpose statements.

The Purpose Statement is a multi-part free-text mandatory entry. It is designed to provide a clear and comprehensive description of the membership of the value set. This important metadata element must take into account how the members will be used in a clinical measure or in any other intended application. The Purpose Statement cannot be validated automatically, so authors should spend time to make this text as informative as possible for human readers to understand the intent of the value set, and how the value set is put together. To avoid redundancy, there should be only one value set for a given purpose. Authors should add Purpose Statements to value sets (whether created or inherited) if they are not present.


The Purpose Statement includes four separate fields that the value set author needs to complete:

  1. Clinical Focus - a free text statement describing the general focus of the value set as it relates to the intended semantic space. This can be the information about clinical relevancy, or the statement about the general focus of the value set, such as a description of types of messages, payment options, geographic locations, etc.
    Example: This set of values contains medications that are prescribed for anticoagulant therapy at hospital discharge for patients following acute ischemic stroke.

    Clinical Focus

  2. Data Element Scope - a free text statement describing how the Data Element in the intended information model defines the concepts to be selected for inclusion in the value set.
    Example: The intent of this data element is to identify patients who are prescribed anticoagulant therapy at discharge following acute ischemic stroke. Using the Quality Data Model, this particular element would map to the "Medication" category.

    Data Element Scope

  3. Inclusion Criteria - Defines what concepts or codes should be included and why.
    Example: Drug forms that are consistent with oral and injectable administration should be included. In this example, the value set authors provided a sample of drugs that are included: Warfarin, heparins, and direct thrombin inhibitors.

    Inclusion Criteria

  4. Exclusion Criteria - Defines what concepts or codes should be excluded and why.
    Example: There is no exclusion criteria listed for this value set.

    Exclusion Criteria