Preloader Icon

Does your organization need to create value sets or groupings/roll-ups of codes from standard terminologies? Do you need to collaborate with colleagues within your organization or with external partners to create and maintain value sets? Do you need a standardized method to distribute value sets so that they can be used by business partners?

If so, the Value Set Authority Center (VSAC) offers a free platform to support these use cases. The VSAC is a repository for public value sets created by external programs and serves as the official repository for all official versions of value sets specified by the Centers for Medicare & Medicaid Services (CMS) electronic Clinical Quality Measures (eCQMs).

Clinical Architecture founded the COVID-19 Interoperability Alliance (Apelon, CareEvolution, Clinical Architecture, Logica, MITRE, National Association of Community Health Centers, Regenstrief Institute, SNOMED, and other collaborators) and is stewarding more than 600 value sets on behalf of our collaborators. These value sets are supporting organizations in their COVID-19 related work including data aggregation, analytics, population cohort identification, clinical trials, and medical research. They have been bundled into six grouping value sets by code system and can be found on the COVID-19 page under the “Clinical Architecture” Steward. Read on to learn about the challenges we encountered as part of this work and some tips and tricks to overcome them.

Getting Started

In order to start creating value sets, or to use ones created by someone else, you first need a UMLS license/account (get one here: Next, you will need to register as a VSAC Author in order to create value sets in VSAC. You’ll also need a VSAC Steward to Approve and Publish your value sets. You can request to be a VSAC Author and/or Steward ( Once your account has been approved, you’re ready to create value sets. There VSAC Support Center is an excellent resource for quickly learning best practices for authoring and stewardship of VSAC value sets (


Before starting to create value sets, take some time to think through the purpose of the value sets, how your value sets will be organized, and how to handle some of the nuances and constraints of the VSAC platform. Once a value set has been published by a Steward, it becomes part of the public domain and can not be deleted; it can be replaced with a new version, although this may require a lot of effort and re-work. Some key considerations are:

Which code system and version(s) are needed?

  • A value set can only have one code system and version.
  • Is your value set definition extensional (enumerated list) or intensional (rule-based)?

Do you need to include provisional codes?

  • These are new codes that have not been officially added to the code system.

Do you need to include retired codes?

  • Retired codes are not active in the current version of the code system.

Do you need to use Grouping value sets?

  • These are a type of value set that is made up of other value sets.

How will you manage your OIDs?

  • Every value set must have a unique OID

What will your value set update process look like?

  • VSAC Authors and Stewards are expected to keep value sets current and suitable for their intended use.

Code System and Version

A value set can have only a single code system and version, although you can combine code systems in a Grouping value set (see Grouping Value Sets). Additionally, the code systems are limited to those made available by the NLM (typically in support of the eCQM program). These constraints can impact how you create, group, and manage value sets, especially if you need to include provisional or retired codes. The Expansion Profile selected when your value set is published will also impact the consistency of the value set’s terms. For example, the default profile “Most Recent Code System Versions in VSAC” will automatically remove terms if they become retired or obsolete when the current version of the code system is released in VSAC. Additionally, new terms will be added to your value set if you used an intensional definition that pulls in terms added in the new code system version. If your intended use requires that your value set remain stable, choose an expansion provided for a specific code version.

Provisional Codes

In our case, there are many brand new codes for COVID-19-related domains (medications, diagnoses, lab tests/results, etc.) that have not been officially added to a terminology. The VSAC team does a great job of identifying provisional codes for the standard code systems supported. These codes can be combined with a value set based on the current code system version (step-by-step instructions here: During our work to publish the COVID-19 value sets, we found a couple of instances where new codes were not yet included in the provisional code list – this was quickly resolved by contacting the VSAC support team and asking for the codes to be added (see Support).

Retired Codes

Some of the use cases for the Alliance’s COVID-19 value sets required that retired codes be included in the value sets. For example, researchers pulling legacy data from their EMR to identify a cohort of patients may need to use retired codes for a medication, procedure, lab test, diagnosis, clinical finding, etc. Retired codes were sometimes used to include people in a cohort and/or exclude them from a measure calculation. See Grouping Value Sets for information on how to combine current and retired codes into a value set.

Grouping Value Sets

These are a type of value set that is made up of other value sets instead of consisting of extensional (enumerated list) or intensional (rule-based) definitions. A Grouping value set will include a list of the OIDs for the value sets to include in the group. Several reasons to create a Grouping value set include:

  • Combining multiple code systems into a group. For example, SNOMED CT, ICD-10-PCS, and HCPCS could be grouped to describe a procedure.
  • Combining multiple code system versions. This technique could be used to group the current code system value set with value sets of retired terms for the same concept.
  • Combining detailed value sets into a more generalized value set. For example, you may create detailed value sets for single ingredient ACE Inhibitor medications, a Grouping value set for single and combination ingredient ACE Inhibitor medications, and another Grouping value set for multiple classes of antihypertensive medications.

Grouping value sets are converted into an enumerated value set composed of the expansion of each of the children value sets included in the group. The Definition page of the Grouping value set will list the OID and name of the children value sets.


Every value set must have a unique OID, and the OID cannot be changed after the value set has been created (even in draft status). VSAC will create an OID for your value set if you don’t explicitly provide one. One benefit of providing your own OID is that consumers can search for, or identify value sets that have been created by your organization based on the root OID value assigned by HL7 to your organization (learn more about OIDs and how to get a root OID for your organization here: If you have accidentally assigned an OID to a value set in error you can’t delete and reuse the OID, however you can RENAME the value set on the Metadata tab at any time and replace the codes in the Definition.

Maintaining Value Sets

VSAC expects that Authors and Stewards will maintain their value sets to keep them current. In our case, VSAC is not our terminology management tool, so we needed a way to determine when new codes should be added to a VSAC value set and when retired codes should be removed (or moved to a new value set – see Retired Codes). VSAC will not allow an Author to duplicate codes, so one simple method is to try to add all the codes in your list to an existing VSAC value set – the downside of this approach is that is has to be done for every value set every time you want to make updates. Another problem is that codes that have been retired are simply ignored unless you use the “validate” feature during the import process. Our solution was to build a utility that compared our source of truth with the most recent version of the corresponding VSAC value set. This tool automates the process of comparing the two value sets and flagging new terms to add and terms that have been retired.


My experience with the VSAC support team has been incredibly positive. The team is very knowledgeable, friendly, and professional. They respond quickly to inquiries, resolve issues in a timely manner, and have offered helpful guidance to our team. The preferred method to contact the support team is to use the “Write to the help desk” button on the top right of this page: This will generate a ticket and email to the support team and send you a copy along with a case number. Please “help them help you” by doing your research, review the content on the VSAC Support Center, learn about the Best Practices, and provide detail and references about your issue or request.


VSAC offers a free platform to create, collaborate, and publish value sets based on standard terminologies. These value sets can be exported into a standardized Excel file format so that they can be easily used by people or imported into software applications. Hopefully, these tips and tricks will help new and aspiring VSAC Authors become power users in record time. Please let me know if these tips are helpful, or if you have additional insights to share with readers.