Run Aidbox locallyRun Aidbox in SandboxTalk to us Ask community

ValueSet

Overview

The ValueSet resource official FHIR documentation can be found here: https://www.hl7.org/fhir/valueset.html.

All examples below can be executed in the REST Console of your Box in Aidbox.Cloud. Just copy/paste a sample into the REST Console and click the EXECUTE button or press Ctrl+Enter.

CRUD

CRUD is fully supported for the ValueSet resource in Aidbox.

POST /ValueSet
content-type: text/yaml

description: The gender of a person used for administrative purposes. 2
compose:
  include:
  - system: http://hl7.org/fhir/administrative-gender
  exclude:
  - system: http://hl7.org/fhir/administrative-gender
    concept:
    - code: other
    - code: unknown
name: AdministrativeGender2
experimental: true
resourceType: ValueSet
status: draft
id: administrative-gender2
url: http://hl7.org/fhir/ValueSet/administrative-gender2
immutable: true

ValueSet Compose Parameters

We will show examples of using the compose element by expanding different value sets.

include.concept

Create a ValueSet using the include.concept element. The result will include only listed concepts: kg and m.

POST /ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: sample-valueset-include-concept
    status: draft
    compose:
      include:
      - system: http://unitsofmeasure.org
        concept:
        - code: kg
          display: kilogram
        - code: m
          display: meter

include.filter

Create a ValueSet using the include.filter element.

Include all concepts from the http://hl7.org/fhir/contact-point-system system where display = "SMS".

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: sample-valueset-include-filter
    url: http://hl7.org/fhir/ValueSet/sample-valueset-include-filter
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/contact-point-system
        filter:
        - {property: display, op: =, value: SMS}

exclude.concept

Create a ValueSet using the exclude.concept element.

Include all concepts from the http://hl7.org/fhir/contact-point-system system and exclude concepts pager, url, and other. Now the value set should include only values phone, fax, email, and sms.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: sample-valueset-exclude-concept
    url: http://hl7.org/fhir/ValueSet/sample-valueset-exclude-concept
    status: draft
    compose:
      include:
      - {system: 'http://hl7.org/fhir/contact-point-system'}
      exclude:
      - concept:
        - {code: pager}
        - {code: other}
        - {code: url}
        system: http://hl7.org/fhir/contact-point-system

exclude.filter

Create a ValueSet using the exclude.filter element.

Include all concepts from the http://hl7.org/fhir/contact-point-system code system and exclude concepts by the filter: exclude all concepts with the length of code = 3 (sms, fax, url). So the value set should include only values: phone, email, pager, and other.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: sample-valueset-exclude-filter
    url: http://hl7.org/fhir/ValueSet/sample-valueset-exclude-filter
    status: draft
    compose:
      include:
      - {system: 'http://hl7.org/fhir/contact-point-system'}
      exclude:
      - system: http://hl7.org/fhir/contact-point-system
        filter:
        - {property: code, op: =, value: '\w{3}'}

include.valueSet

Selects concepts found in this value set. This is an absolute URI that is a reference to ValueSet.url.

concept and filter don't apply to valueSet.

N/B: ValueSet.compose.include.valueSet **** should be an array not a string.

Let's include the administrative-gender value set. There will be 4 concepts: male, female, unknown, and other.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-from-valueset
    url: http://hl7.org/fhir/ValueSet/valueset-from-valueset
    status: draft
    compose:
      include:
      - valueSet: ['http://hl7.org/fhir/ValueSet/administrative-gender']

exclude.valueSet

Let's exclude administrative-gender2 which consists of male and female from administrative-gender code system. The result will be 2 values: other and unknown.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-exclude-valueset
    url: http://hl7.org/fhir/ValueSet/valueset-exclude-valueset
    status: draft
    compose:
      include:
      - {system: 'http://hl7.org/fhir/administrative-gender'}
      exclude:
      - valueSet: ['{{base}}/ValueSet/administrative-gender2']

Filter Operations

The filter.op element defines the kind of operation to perform as a part of the filter criteria. It can take one of the following values:

Code
Display
Support

=

Equals

Supported

is-a

Is A (by subsumption)

Supported

descendent-of

Descendent Of (by subsumption)

Supported

is-not-a

Not (Is A) (by subsumption)

Supported

regex

Regular Expression

Supported

in

In Set

Supported

not-in

Not in Set

Supported

generalizes

Generalizes (by Subsumption)

Not supported

exists

Exists

Supported

In the examples below we will use the goal-status code system which consists of :

Code
Parent codes

accepted

-

achieved

["accepted"]

ahead-of-target

["accepted", "in-progress"]

behind-target

["accepted", "in-progress"]

cancelled

-

entered-in-error

-

in-progress

["accepted"]

on-hold

["accepted"]

on-target

["accepted", "in-progress"]

planned

["accepted"]

proposed

-

rejected

-

sustaining

["accepted", "in-progress"]

Equals

Let's include only concepts with the specified property code equals the provided value cancelled. The result will include only one concept: cancelled.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-equals
    url: http://hl7.org/fhir/ValueSet/valueset-filter-equals
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: code, op: =, value: cancelled}

Is A (by subsumption)

Let's include all concepts that have a transitive is-a relationship with the concept code in-progress provided as the value including the provided concept itself (i.e. include self and child codes). The result will include 5 values: in-progress, on-target, ahead-of-target, behind-target, and sustaining.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-is-a
    url: http://hl7.org/fhir/ValueSet/valueset-filter-is-a
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: code, op: is-a, value: in-progress}

Descendent Of (by subsumption)

Let's include all concepts that have a transitive is-a relationship with the concept code in-progress provided as the value excluding the provided concept itself (i.e. include child codes). The result will include 4 values: on-target, ahead-of-target, behind-target, and sustaining.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-descendent-of
    url: http://hl7.org/fhir/ValueSet/valueset-filter-descendent-of
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: code, op: descendent-of, value: in-progress}

Not (Is A) (by subsumption)

Let's include all codes where the specified property of the code does not have an is-a relationship with the provided value accepted. The result will include 4 values whose parent is not accepted: proposed, cancelled, rejected, and entered-in-error.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-is-not-a
    url: http://hl7.org/fhir/ValueSet/valueset-filter-is-not-a
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: code, op: is-not-a, value: accepted}

Regular Expression

Aidbox supports filter operation regex and implements Postgresql regular expressions. See the documentation here: https://www.postgresql.org/docs/9.3/static/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP.

Please notice that regular expressions require an additional character escaping in JSON.

Let's include codes where the specified property of the code matches the regex specified in the provided value \\w{8}. The result will include 4 values that have 8 symbols in length: proposed, accepted, achieved, and rejected.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-equals
    url: http://hl7.org/fhir/ValueSet/valueset-filter-equals
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: code, op: regex, value: '\w{8}'}

In Set

Let's include concepts where the specified property of the code is in the set of codes specified in the provided value on-target,ahead-of-target,behind-target (comma separated list). The result will be 3 values: on-target, ahead-of-target, and behind-target.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-in
    url: http://hl7.org/fhir/ValueSet/valueset-filter-in
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: code, op: in, value: 'on-target,ahead-of-target,behind-target'}

Not in Set

Let's include concepts where the specified property of the code is not in the set of codes specified in the provided value accepted,achieved,ahead-of-target,behind-target,cancelled,entered-in-error,in-progress,on-hold,on-target,planned (comma separated list). The result will include 3 values: proposed, rejected, and sustaining.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-not-in
    url: http://hl7.org/fhir/ValueSet/valueset-filter-not-in
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: code, op: not-in, value: 'accepted,achieved,ahead-of-target,behind-target,cancelled,entered-in-error,in-progress,on-hold,on-target,planned'}

Generalizes (by Subsumption)

This parameter is not supported in Aidbox.

Exists

The specified property of the code has at least one value (if the specified value is true; if the specified value is false, then matches when the specified property of the code has no values).

Let's display concepts where property hierarchy exists. The result will include 8 concepts for which hierarchy is not an empty array: achieved, ahead-of-target, behind-target, in-progress, on-hold, on-target, planned, and sustaining.

POST {{base}}/ValueSet/$expand
content-type: text/yaml

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    id: valueset-filter-exists
    url: http://hl7.org/fhir/ValueSet/valueset-filter-exists
    status: draft
    compose:
      include:
      - system: http://hl7.org/fhir/goal-status
        filter:
        - {property: hierarchy, op: exists, value: true}

Operations

FHIR specification
Status
Documentation and samples

$expand

supported

ValueSet Expansion

$validate-code

supported

ValueSet Code validation

PreviousCodeSystem Code CompositionNextValueSet Expansion

Last updated

#2416:

Change request updated