ValueSet Expansion

Overview

$expand operation expand given ValueSet in to set of concepts. For more information see official documentation FHIR Terminology ValueSet Expansion

Api

GET/POST URL: [base]/ValueSet/$expand
GET/POST URL: [base]/ValueSet/[id]/$expand

Example for expand default AdministrativeGender ValueSet. List of default ValueSets.

GET [base]/ValueSet/administrative-gender/$expand

Parameters

Parameter

Type

Status

Example

url

uri

supported

url

valueSet

ValueSet

supported

valueSet

context

uri

not supported

-

filter

string

supported

filter

profile

uri

not supported

-

date

dateTime

not supported

-

offset

integer

supported

offset

count

integer

supported

count

includeDesignations

boolean

not supported

-

includeDefinition

boolean

not supported

-

activeOnly

boolean

supported

activeOnly

excludeNested

boolean

not supported

-

excludeNotForUI

boolean

not supported

-

excludePostCoordinated

boolean

not supported

-

displayLanguage

code

not supported

-

limitedExpansion

boolean

not supported

-

url

A canonical url for a value set.

Request
Response
GET [base]/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/administrative-gender

Or

POST [base]/ValueSet/$expand
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "url",
"valueUri" : "http://hl7.org/fhir/ValueSet/administrative-gender"
}
]
}
{
"id": "administrative-gender",
"resourceType": "ValueSet",
"url": "http://hl7.org/fhir/ValueSet/administrative-gender",
"description": "The gender of a person used for administrative purposes.",
"compose": {
"include": [
{
"system": "http://hl7.org/fhir/administrative-gender"
}
]
},
"name": "AdministrativeGender",
"expansion": {
"timestamp": "2018-09-25T16:24:55Z",
"identifier": "http://hl7.org/fhir/ValueSet/administrative-gender",
"contains": [
{
"code": "male",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Male",
"definition": "Male"
},
{
"code": "female",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Female",
"definition": "Female"
},
{
"code": "other",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Other",
"definition": "Other"
},
{
"code": "unknown",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Unknown",
"definition": "Unknown"
}
]
},
......
}

valueSet

The value set is provided directly as part of the request.

Request
Response
POST [base]/ValueSet/$expand
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "valueSet",
"resource" : {
"resourceType": "ValueSet",
"url": "http://custom/administrative-gender",
"compose": {
"include": [
{
"valueSet": ["http://hl7.org/fhir/ValueSet/administrative-gender"]
}
]
}
}
}
]
}
{
"resourceType": "ValueSet",
"url": "http://custom/administrative-gender",
"compose": {
"include": [
{
"valueSet": [
"http://hl7.org/fhir/ValueSet/administrative-gender"
]
}
]
},
"expansion": {
"timestamp": "2018-09-26T08:51:30Z",
"identifier": "http://custom/administrative-gender",
"contains": [
{
"code": "male",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Male",
"definition": "Male"
},
{
"code": "female",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Female",
"definition": "Female"
},
{
"code": "other",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Other",
"definition": "Other"
},
{
"code": "unknown",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Unknown",
"definition": "Unknown"
}
]
}
}

filter

A text filter that is applied to restrict the codes

Request
Response
GET [base]/ValueSet/administrative-gender/$expand?filter=male

Or

POST [base]/ValueSet/administrative-gender/$expand
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "filter",
"valueString" : "male"
}
]
}
{
"id": "administrative-gender",
"resourceType": "ValueSet",
"url": "http://hl7.org/fhir/ValueSet/administrative-gender",
"description": "The gender of a person used for administrative purposes.",
"compose": {
"include": [
{
"system": "http://hl7.org/fhir/administrative-gender"
}
]
},
"name": "AdministrativeGender",
"expansion": {
"timestamp": "2018-09-25T16:24:55Z",
"identifier": "http://hl7.org/fhir/ValueSet/administrative-gender",
"contains": [
{
"code": "male",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Male",
"definition": "Male"
},
{
"code": "female",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Female",
"definition": "Female"
}
]
},
......
}

offset

Paging support - where to start if a subset is desired (default = 0).

Request
Response
GET [base]/ValueSet/administrative-gender/$expand?offset=2

Or

POST [base]/ValueSet/administrative-gender/$expand
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "offset",
"valueInteger" : 2
}
]
}
{
"id": "administrative-gender",
"resourceType": "ValueSet",
"url": "http://hl7.org/fhir/ValueSet/administrative-gender",
"description": "The gender of a person used for administrative purposes.",
"compose": {
"include": [
{
"system": "http://hl7.org/fhir/administrative-gender"
}
]
},
"name": "AdministrativeGender",
"expansion": {
"timestamp": "2018-09-25T16:24:55Z",
"identifier": "http://hl7.org/fhir/ValueSet/administrative-gender",
"contains": [
{
"code": "other",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Other",
"definition": "Other"
},
{
"code": "unknown",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Unknown",
"definition": "Unknown"
}
]
},
......
}

count

Paging support - how many codes should be provided in a partial page view.

Request
Response
GET [base]/ValueSet/administrative-gender/$expand?count=1

Or

POST [base]/ValueSet/administrative-gender/$expand
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "count",
"valueInteger" : 1
}
]
}
{
"id": "administrative-gender",
"resourceType": "ValueSet",
"url": "http://hl7.org/fhir/ValueSet/administrative-gender",
"description": "The gender of a person used for administrative purposes.",
"compose": {
"include": [
{
"system": "http://hl7.org/fhir/administrative-gender"
}
]
},
"name": "AdministrativeGender",
"expansion": {
"timestamp": "2018-09-25T16:24:55Z",
"identifier": "http://hl7.org/fhir/ValueSet/administrative-gender",
"contains": [
{
"code": "male",
"module": "fhir-3.3.0",
"system": "http://hl7.org/fhir/administrative-gender",
"display": "Male",
"definition": "Male"
}
]
},
......
}

activeOnly

Controls whether inactive concepts are included or excluded in value set expansions.

For example we are create testing ValueSet with one current active concept and one deprecated concept provided directly as part of the request.

Get all concepts

Request
Response
POST [base]/ValueSet/$expand
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "activeOnly",
"valueBoolean": false
},
{
"name" : "valueSet",
"resource" : {
"resourceType": "ValueSet",
"url": "http://custom/testing",
"compose": {
"include": [
{"system": "http://testing",
"concept": [{"code": "active"},
{"code": "inactive",
"deprecated": true}]
}
]
}
}
}
]
}
{
"resourceType": "ValueSet",
"url": "http://custom/testing",
"compose": {
"include": [
{
"system": "http://testing",
"concept": [
{
"code": "active"
},
{
"code": "inactive",
"deprecated": true
}
]
}
]
},
"expansion": {
"timestamp": "2018-09-26T09:19:03Z",
"identifier": "http://custom/testing",
"contains": [
{
"code": "active",
"system": "http://testing"
},
{
"code": "inactive",
"system": "http://testing",
"deprecated": true
}
]
}
}

Get only active concepts

Request
Response

Get only active concepts

POST [base]/ValueSet/$expand
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "activeOnly",
"valueBoolean": true
},
{
"name" : "valueSet",
"resource" : {
"resourceType": "ValueSet",
"url": "http://custom/testing",
"compose": {
"include": [
{"system": "http://testing",
"concept": [{"code": "active"},
{"code": "inactive",
"deprecated": true}]
}
]
}
}
}
]
}
{
"resourceType": "ValueSet",
"url": "http://custom/testing",
"compose": {
"include": [
{
"system": "http://testing",
"concept": [
{
"code": "active"
},
{
"code": "inactive",
"deprecated": true
}
]
}
]
},
"expansion": {
"timestamp": "2018-09-26T09:19:03Z",
"identifier": "http://custom/testing",
"contains": [
{
"code": "active",
"system": "http://testing"
}
]
}
}