Tutorials

Use Cases

Interface

Examples & Testing

Endpoints

Using ValueSets

HIEBus stores an up-to-date library of ‘Reference’ Value Sets maintained by CareEvolution’s terminology service, Rosetta, from a variety of sources including the code system publishers (e.g., LOINC, RxNorm), public programs (e.g., CMS), and quality/public health/population health organizations (e.g., AHRQ, CDC, NCQA). A value set contains a collection of codes from one or more code systems with a particular common meaning. Value sets have a ‘scope’ based on the publisher/program (e.g., CCSR Category, LOINC-Component), domain (e.g., COVID19), date (e.g., MeasureTerms_MY2020), and/or intended use (e.g., MedRT - May Treat).

Value sets are used to serve several different functions:

  • Categorization (e.g., grouping Problems into chronic vs. acute)
  • Attributes (e.g., identifying Medication ingredients)
  • Filtering/Querying (e.g., finding discharge summaries within Reports)

Contents

Using Value Sets as a Query Parameter

Value sets can be used to filter queries using ?[FIELD_NAME]:in=[VALUESET_URI] for several resources, particularly:

  • Encounter?class:in=, Encounter?type:in=
  • Condition?code:in=
  • DiagnosticReport?code:in=
  • Observation?code:in
  • MedicationDispense?code:in, MedicationAdministration?code:in, MedicationRequest?code:in
  • Immunization?vaccine-code:in
  • Procedure?code:in

For example, to query for a discharge summary:

GET https://[YOUR_FHIR_ENDPOINT]/DiagnosticReport?patient=[PATIENT ID]&_count=10&code:in=https://rosetta.careevolution.com/subsets/LOINC-Component/Discharge summary [Component]

Multiple value sets can be included in a comma-delimited list interpreted as ‘OR’.

Retrieving Available Value Sets & URIs

Available value sets within a scope can be retrieved with a GET search operation.

GET https://[YOUR_FHIR_ENDPOINT]/ValueSet?version=[VALUESET_SCOPE]&_summary=true

This will retrieve a Bundle of ValueSets. The VALUESET_URI will be populated in the resource.ValueSet.url property of each ValueSet and is useful in subsequent requests.

<Bundle xmlns="http://hl7.org/fhir">
    <type value="searchset" />
    ...
    <entry>
        <fullUrl value="https://[YOUR_FHIR_ENDPOINT]/ValueSet/1.146355" />
        <resource>
            <ValueSet>
                <id value="1.146355" />
                <meta>
                    <tag>
                        <system value="http://terminology.hl7.org/CodeSystem/v3-ObservationValue" />
                        <code value="SUBSETTED" />
                    </tag>
                </meta>
                <url value="https://rosetta.careevolution.com/subsets/LOINC-Component/Referral%20lab%20test%20reference%20range%20%5BComponent%5D" />
                <version value="LOINC-Component" />
                <name value="Referral lab test reference range [Component]" />
                <status value="active" />
            </ValueSet>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
    ...

Common value set scopes

The most commonly used value set scopes available in HIEBus are listed below.

Domain Value Set Scope Description Reference
Problems CCSR Category Groups ICD-10-CM problems into clinically-relevant higher level categories AHRQ Clinical Classifications
Software Refined
  CCI Acute vs. Chronic classification of ICD-10-CM AHRQ Chronic
Condition Indicator
  MeSH Diagnostic Group Categorization of ICD-10-CM and SNOMED used in PubMed Medical Subject Headings
  HCC-v24 Latest version of ICD-10-CM grouping system used for Medicare Risk Adjustment CMS
Procedures HCPCS-Categories Grouping of HCPCS Level II codes CMS
  HCProcedureCategory High level clinically-relevant grouping of HCPCS codes CareEvolution Proprietary
  CCSProcCategory-ForACOMeasures Detailed grouping of ICD-10-PCS codes AHRQ Clinical Classification Software (deprecated)
Healthcare Setting HCSetting Grouping of place of service (CMS), facility type (UB-04), claim type (FHIR), act code (FHIR), and encounter class (FHIR) codes (e.g., Inpatient, SNF-LTC for skilled nursing facility/long-term care) CareEvolution Proprietary
Labs, Vitals, and Reports/Notes http://terminology.hl7.org/CodeSystem/observation-category LOINC and SNOMED categorized into high-level categories (e.g., imaging, vital-signs) HL7 FHIR
  LOINC-Component The analyte or attribute being measured or observed (e.g., Sodium, Body weight, Discharge summary note) LOINC Component
(Search:here)
  LOINC-Class (e.g., CARD-US for cardiac ultrasound, RAD for radiology, HEM/BC for hematology/blood chemistry) LOINC Class
(Search:here)
  LOINC-ClassType Four ClassTypes: 1=Laboratory, 2=Clinical, 3=ClaimsAttachment, 4=Surveys LOINC ClassType
(Search:here)
  LOINC-MethodType e.g., IA for immunoassay, Visual for visual count LOINC MethodType
(Search:here)
  LOINC-Property e.g., Mass, Num for count, MCnc for mass concentration LOINC Property
(Search:here)
  LOINC-ScaleType e.g., Qn for quantitative, Nar for narrative, Doc for document LOINC ScaleType
(Search:here)
  LOINC-System e.g., Bld for blood, Liver LOINC System
(Search:here)
  LOINC-TimeAspect e.g., Pt for point in time, 24H for 24 hours LOINC TimeAspect
(Search:here)
Medications RxNorm - ATC Multi-level grouping of medications by ingredient class and clinical use WHO Anatomical Therapeutic Chemical
  RxNorm - Brands Brand name of medication (not potential brands of generic; actual brand of specific RxNorm medication) RxNorm (TTY=BN)
  RxNorm - Ingredient Ingredient for included RxNorm codes (each code can be included in multiple value sets) RxNorm (TTY=IN)
  RxNorm - Multi Ingredient Ingredients for included RxNorm codes (each code will be found in a single value set; only contains codes for medications that have multiple ingredients) RxNorm (TTY=MIN)
  RxNorm - Strength Strength (e.g., 25MG) for included RxNorm codes RxNorm (TTY=DF)
  RxNorm - Contraindicating Class Class of meds (value set name) contraindicated by medication (included RxNorm code) MedRT (CI_ChemClass)
  RxNorm - Contraindicating Mechanism of Action MOA (value set name) for meds contraindicated by included RxNorm codes MedRT (CI_MoA)
  RxNorm - Contraindicating Physiologic Effect PE (value set name) for meds contraindicated by included RxNorm codes MedRT (CI_PE)
  RxNorm - Dose Form Dose form (e.g., tablet, injection) for included RxNorm codes RxNorm (TTY=DF)
  RxNorm - Mechanism Of Action MoA for included RxNorm codes MedRT (has_MoA)
  RxNorm - Pharmacologic Action PA for included RxNorm codes MeSH
  RxNorm - Therapeutic Class TC (e.g., Antibacterial agent) for included RxNorm codes FMT/MedRT (has_TC)
  RxNorm - VA Drug Class High level chemical and clinical use groupings of included RxNorm codes VA (has_VAClass)
  MedRT - May Treat Diseases (as MeSH Diagnostic Group value set names) related to included RxNorm codes MedRT (may_treat)
  MedRT - May Prevent Diseases (as MeSH Diagnostic Group value set names) related to included RxNorm codes MedRT (may_prevent)
  MedRT - May Induce Diseases (as MeSH Diagnostic Group value set names) related to included RxNorm codes MedRT (may_induce)
  RxNorm - ATC Multi-level grouping of medications by ingredient class and clinical use WHO Anatomical Therapeutic Chemical
Provider Specialties ProviderTaxonomy-Grouping High-level grouping of provider types and specialties National Uniform Claim Committee
  ProviderTaxonomy-Classification Detailed grouping of provider types and specialties National Uniform Claim Committee
COVID19 COVID-19 Value sets: CareEvolution Proprietary (Published)
    COVID19 Confirmed Infection
ICD-10-CM and SNOMED codes indicating confirmed infection based on official CDC and WHO guidance		  
    COVID19 Suspected Infection
Broader set of ICD-10-CM and SNOMED codes indicating suspected/likely infection (does not include Confirmed codes)		  
    COVID19 Potential Exposure
ICD9, ICD-10-CM, and SNOMED codes indicating exposure		  
    COVID19 Potential Signs and Symptoms
ICD-10-CM, SNOMED, and LOINC codes containing long list of associated conditions based on CDC guidance		  
    COVID19 Encounters
ICD-10-CM, HCPCS, LOINC, and SNOMED codes based on official guidance		 [
    COVID19 Lab Tests Antigen
LOINC and SNOMED codes containing all known antigen (virus/infection) tests		  
    COVID19 Lab Tests Antigen
LOINC and SNOMED codes containing all known antibody tests		  
    COVID19 Vaccination
CVX, NDC, RxNorm, HCPCS, LOINC, and SNOMED codes containing all known vaccinations		  

Classifying Codes with Value Sets ($classify operation)

Many use cases can leverage value sets to categorize codes or retrieve additional attributes of codes. The $classify operation takes one or more codes from a single code system via POST of a Parameters resource and returns the list of value sets to which each of those codes belongs, within a given value set scope.

For example, POST https://[YOUR_FHIR_ENDPOINT]/ValueSet/$classify with the following body:

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "system",
            "valueString": "http://www.nlm.nih.gov/research/umls/rxnorm"
        },
        {
            "name": "version",
            "valueString": "RxNorm - Mechanism Of Action"
        },
        {
            "name": "code",
            "valueString": "198145"
        },
        {
            "name": "code",
            "valueString": "387003"
        },
        {
            "name": "code",
            "valueString": "317160"
        }
        ...
      ]
}


See the FHIR documentation for the complete specification for the ValueSet Resource.

Retrieving Codes Contained within a Value Set

The full contents of a ValueSet can be retrieved with a GET call.

GET https://[YOUR_FHIR_ENDPOINT]/ValueSet?version=[VALUESET_SCOPE]&name=[VALUESET_NAME]&_count=10

For example, GET https://[YOUR_FHIR_ENDPOINT]/ValueSet?version=LOINC-Component&name=Discharge summary [Component]&_count=10 will return:

<Bundle xmlns="http://hl7.org/fhir">
    <type value="searchset" />
    <link>
        <relation value="self" />
        <url value="https://[YOUR_FHIR_ENDPOINT]/ValueSet?name=Discharge%20summary%20%5BComponent%5D&amp;version=LOINC-Component&amp;_count=10" />
    </link>
    <entry>
        <fullUrl value="https://[YOUR_FHIR_ENDPOINT]/ValueSet/1.99245" />
        <resource>
            <ValueSet>
                <id value="1.99245" />
                <meta>
                    <lastUpdated value="2021-05-24T18:50:58.72Z" />
                </meta>
                <url value="https://rosetta.careevolution.com/subsets/LOINC-Component/Discharge%20summary%20note%20%5BComponent%5D" />
                <version value="LOINC-Component" />
                <name value="Discharge summary note [Component]" />
                <status value="active" />
                <compose>
                    <include>
                        <system value="http://loinc.org" />
                        <concept>
                            <extension url="http://careevolution.com/fhirextensions#valueSet-family">
                                <valueString value="Reference" />
                            </extension>
                            <code value="11490-0" />
                            <display value="MD Discharge sum" />
                        </concept>
                        <concept>
                            <extension url="http://careevolution.com/fhirextensions#valueSet-family">
                                <valueString value="Reference" />
                            </extension>
                            <code value="18842-5" />
                            <display value="Discharge sum" />
                        </concept>
                      ...

Have questions about the HIEBus FHIR interface? Contact us at fhir@careevolution.com.

Terms of Use

© 2023 CareEvolution, LLC