ValueSet Resource
GET /terminology/v1/fhir/r4/ValueSet/
The ValueSet resource represents a collection of codes from one or more CodeSystems.
Contents
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 Rosetta 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 Rosetta 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.rosetta.careevolution.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.
{
"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 Rosetta 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.
When searching ValueSets the
_summary=true flag is required.
GET https://api.rosetta.careevolution.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.
{
"resourceType": "Bundle",
"id": "31733a2b-14f2-4eac-90a3-e35a2f47ac0a",
"type": "searchset",
"total": 13344,
"entry": [
{
"id": "RxNorm-Ingredient-44",
"fullUrl": "https://api.rosetta.careevolution.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.rosetta.careevolution.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.rosetta.careevolution.com/terminology/v1/fhir/r4/ValueSet/RxNorm-Ingredient-29046
{
"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.
Rosetta value sets contain only reference codes. It is therefore adviseable 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/ndcor 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 |
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.rosetta.careevolution.com/terminology/v1/fhir/r4/ValueSet/$classify
with 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:
{
"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"
}
]
}
]
}
]
}