GET /terminology/v1/fhir/r4/ValueSet/
The ValueSet
resource represents a collection of codes from one or more CodeSystems
.
Contents
The codes are grouped together to represent a general concept that encompasses a set of codes. Some examples may be:
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.
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"
},
...
]
}
]
}
}
The most commonly used value set scopes available in Rosetta are listed in Commonly Used Value Set Scopes.
Once a useful scope is selected, the set of ValueSets that scope describes can be retrieved with a GET
search operation.
_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"
}
},
...
]
}
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"
},
...
]
}
]
}
}
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:
/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 |
$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"
}
]
}
]
}
]
}