ValueSet Expansion

Overview

$expand operation expand given ValueSet in to set of concepts. For more information, see the 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

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

Or

POST [base]/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- {name: url, valueUri: 'http://hl7.org/fhir/ValueSet/administrative-gender'}

Response

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 a part of the request.

Request

POST [base]/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    url: http://custom/administrative-gender
    compose:
      include:
      - valueSet: ['http://hl7.org/fhir/ValueSet/administrative-gender']

Response

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

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

Or

POST [base]/ValueSet/administrative-gender/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- {name: filter, valueString: male}

Response

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

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

Or

POST [base]/ValueSet/administrative-gender/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- {name: offset, valueInteger: 2}

Response

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

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

Or

POST [base]/ValueSet/administrative-gender/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- {name: count, valueInteger: 1}

Response

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 create a testing ValueSet with one current active concept and one deprecated concept provided directly as a part of the request.

Get all concepts

Request

POST [base]/ValueSet/$expand
content-type: text/yaml

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}

Response

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

Get only active concepts

POST [base]/ValueSet/$expand
content-type: text/yaml

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}

Response

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'}