ValueSet Resource

GET /terminology/v1/fhir/r4/ValueSet/

The ValueSet resource represents a collection of codes from one or more CodeSystems.

Contents

Using ValueSets
Get the List of All Available ValueSet Scopes
Commonly Used Value Set Scopes
Get All ValueSets Within a Given Scope
Get a Complete ValueSet Given a ValueSet ID
Get the ValueSet Memberships for Reference Codes ($classify)

Using ValueSets

The codes are grouped together to represent a general concept that encompasses a set of codes. Some examples may be:

RxNorm and NDC codes for medications containing Oxycodone.
SNOMED and ICD-10-CM codes for Type 2 Diabetes without complications.
The set of lab tests and procedure codes representing Covid-19 antibody tests.

In the Terminology API, an extension with url https://rosetta.careevolution.com/fhir/ValueSet/Extension/Scope is used to categorize ValueSets 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).

Please see the FHIR documentation for the complete specification for the ValueSet Resource. Some common operations are summarized below.

Get the List of All Available ValueSet Scopes

The Terminology API has a unique ValueSet with id Rosetta.ValueSetScopes that contains a list of all scopes available on the server. To retrieve this ValueSet use a GET call and specify the id.

GET https://api.careevolutionapi.com/terminology/v1/fhir/r4/ValueSet/Rosetta.ValueSetScopes

This will retrieve a ValueSet populated with a set of codes - each code representing a scope available on the server.

Sample Response

{
    "resourceType": "ValueSet",
    "id": "Rosetta.ValueSetScopes",
    "url": "https://rosetta.careevolution.com/fhir/ValueSet/Rosetta.ValueSetScopes",
    "name": "Rosetta.ValueSetScopes",
    "compose": {
        "include": [
            {
                "system": "http://careevolution.com/rosetta/value-set-scopes",
                "concept": [
                    {
                        "code": "`RxNorm - Ingredient"
                    },
                    {
                        "code": "`RxNorm - ATC"
                    },
                    ...
                    ]
            }
        ]
    }
}

Commonly Used Value Set Scopes

The most commonly used value set scopes available in Orchestrate are listed in Commonly Used Value Set Scopes.

Get All ValueSets Within a Given Scope

Once a useful scope is selected, the set of ValueSets that scope describes can be retrieved with a GET search operation.

Tip
When searching ValueSets the _summary=true flag is required.

GET https://api.careevolutionapi.com/terminology/v1/fhir/r4/ValueSet/?extension.scope=RxNorm - Ingredient&_summary=true

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

Sample Response

{
    "resourceType": "Bundle",
    "id": "31733a2b-14f2-4eac-90a3-e35a2f47ac0a",
    "type": "searchset",
    "total": 13344,
    "entry": [
        {
            "id": "RxNorm-Ingredient-44",
            "fullUrl": "https://api.careevolutionapi.com/terminology/v1/fhir/r4/ValueSet/RxNorm-Ingredient-44",
            "resource": {
                "resourceType": "ValueSet",
                "id": "RxNorm-Ingredient-44",
                "extension": [
                    {
                        "url": "https://rosetta.careevolution.com/fhir/ValueSet/Extension/Scope",
                        "valueString": "RxNorm - Ingredient"
                    },
                    {
                        "url": "https://rosetta.careevolution.com/fhir/ValueSet/Extension/Source",
                        "valueString": "RxNorm"
                    }
                ],
                "version": "210503.0.0",
                "name": "mesna"
            }
        },
        {
            "id": "RxNorm-Ingredient-61",
            "fullUrl": "https://api.careevolutionapi.com/terminology/v1/fhir/r4/ValueSet/RxNorm-Ingredient-61",
            "resource": {
                "resourceType": "ValueSet",
                "id": "RxNorm-Ingredient-61",
                "extension": [
                    {
                        "url": "https://rosetta.careevolution.com/fhir/ValueSet/Extension/Scope",
                        "valueString": "RxNorm - Ingredient"
                    },
                    {
                        "url": "https://rosetta.careevolution.com/fhir/ValueSet/Extension/Source",
                        "valueString": "RxNorm"
                    }
                ],
                "version": "210503.0.0",
                "name": "beta-alanine"
            }
        },
        ...
    ]
}

Get a Complete ValueSet Given a ValueSet ID

Once a target ValueSet id is found, getting the full contents of the ValueSet can be done with a GET call specifying the id retrieved in a prior request. This will return the complete ValueSet.

GET https://api.careevolutionapi.com/terminology/v1/fhir/r4/ValueSet/RxNorm-Ingredient-29046

Sample Response

{
    "resourceType": "ValueSet",
    "id": "RxNorm-Ingredient-29046",
    "extension": [
        {
            "url": "https://rosetta.careevolution.com/fhir/ValueSet/Extension/Scope",
            "valueString": "RxNorm - Ingredient"
        },
        {
            "url": "https://rosetta.careevolution.com/fhir/ValueSet/Extension/Source",
            "valueString": "RxNorm"
        }
    ],
    "version": "210503.0.0",
    "name": "lisinopril",
    "compose": {
        "include": [
            {
                "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                "concept": [
                    {
                        "code": "29046",
                        "display": "lisinopril"
                    },
                    {
                        "code": "85783",
                        "display": "Zestoretic"
                    },
                ...
                ]
            }
        ]
    }
}

Get the ValueSet Memberships for Reference Codes ($classify)

In some situations it is useful to get the ValueSet(s) that a list of codes are members of. This can be used to categorize or group codes by ValueSet membership. For example, you may wish to:

Categorize a collection of NDC drug codes by their active ingredient.
Categorize a collection of LOINC lab tests by the component they are measuring.
Categorize a collection of ICD-10-CM Diagnoses into a broad set of disease groupings.

Tip
Orchestrate value sets contain only reference codes. It is therefore advisable to use /ConceptMap/$translate operation on source data prior to using the /ValueSet/$classify operation if you are starting with uncoded source data.

This can be achieved by using the custom $classify operation. The $classify operation accepts POST requests with a Parameters resource in the body of the request.

The parameters passed to the operation must have the following fields:

Parameter Name	Type	How Many	Description	Sample Values
`system`	string	1	The CodeSystem.url of your collection of codes.	`http://hl7.org/fhir/sid/ndc`or `http://hl7.org/fhir/sid/icd-10-cm`
`scope`	string	0-1	The ValueSet scope that you are interested in. If not supplied, the system will return all ValueSets that the codes are members of.	`RxNorm - Ingredient` or `MeSH Diagnostic Group`
`code`	string	1-100	One of the codes you wish to categorize.	`00591040501` or `E11.9`

Tip
The $classify operation will classify a set of codes from a single CodeSystem. If you wish to classify two sets of codes from two CodeSystems, you will need to call the operation once for each set of codes.

The operation will return a Parameters resource with a collection of items representing the classification groups for each code

For example,POST https://api.careevolutionapi.com/terminology/v1/fhir/r4/ValueSet/$classify with body:

Body

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "system",
            "valueString": "http://hl7.org/fhir/sid/ndc"
        },
        {
            "name": "scope",
            "valueString": "RxNorm - Ingredient"
        },
        {
            "name": "code",
            "valueString": "00591040501"
        },
        {
            "name": "code",
            "valueString": "37808024602"
        }
    ]
}

will respond with:

Response

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "item",
            "part": [
                {
                    "name": "code",
                    "valueString": "00591040501"
                },
                {
                    "name": "classification",
                    "part": [
                        {
                            "name": "scope",
                            "valueString": "RxNorm - Ingredient"
                        },
                        {
                            "name": "name",
                            "valueString": "lisinopril"
                        }
                    ]
                }
            ]
        },
        {
            "name": "item",
            "part": [
                {
                    "name": "code",
                    "valueString": "37808024602"
                },
                {
                    "name": "classification",
                    "part": [
                        {
                            "name": "scope",
                            "valueString": "RxNorm - Ingredient"
                        },
                        {
                            "name": "name",
                            "valueString": "aspirin"
                        }
                    ]
                }
            ]
        }
    ]
}