Skip to main content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

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 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 CMS71v10 uses three value sets, ICD-9-CM, ICD-10-CM, and SNOMED CT. All of these member value sets 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

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 Active in the Code System: The authors should consider only currently active codes for inclusion into a value set, unless inactive codes have been intentionally included in the value set to facilitate a look back period. This assures proper maintenance of the value sets.
  • 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:

  • Write the value set name to convey the specific distinguishing characteristics of the member concepts.
  • 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.
  • Use sufficiently descriptive names. Using the example above, 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.
  • Use correct spelling and grammar
  • 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 value set, unless the program name 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.
  • Do not use the word "Other" as an alternative to another value set. Each value set name must be understandable independent of any other value set. For example: Do not name a value set "Other Endophthalmitis" just because a value set named "Purulent Endophthalmitis" already exists. Be as specific as possible. "Other Endophthalmitis" lacks adequate information that value set consumers need.
  • 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 describe how to use the concept 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 must add Purpose Statements to value sets 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 including a description of the intended constituent concepts. This can include information about clinical relevancy or a statement about the general focus of the value set, such as a description of types of messages, payment options, geographic locations, etc. Note that over the course of a value set’s lifecycle value set authors should not change the clinical focus in any meaningful way.
    Example (from the CMS eCQM program): The purpose of this value set is to represent concepts for conjugated estrogen/medroxyprogesterone combination medications.

  2. Data Element Scope - A free text statement describing how the data element relates to the value set it is bound to. This context of usage often constrains the semantic type of the allowed constituent concepts.
    Example (from the CMS eCQM program): This value set may use a model element in the QDM category of Medication.

  3. Inclusion Criteria - A free text statement that describes what specific concept or code criteria are included and why.
    Example (from the CMS eCQM program) Includes concepts that describe a medication specific to generic, prescribable esterified estrogen medication.

  4. Exclusion Criteria - A free text statement that describes what specific concept or code criteria would normally be included, but are specifically excluded by the value set author, including their rationale for exclusions. If the value set author determines there are no identified exclusions, they should populate this field with the text “No exclusions‮
    Example (from the CMS eCQM program): Excludes concepts that describe branded and non-prescribable esterified estrogen medications in combination with other medication.

Last Reviewed: April 23, 2021