R4
Ballot
#1
#2
(Mixed
Normative/Trial
use)
Terminology
This
page
is
part
of
the
FHIR
Specification
(v3.3.0:
(v3.5.0:
R4
Ballot
2).
#2).
The
current
version
which
supercedes
this
version
is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
|
Vocabulary
Work
Group
|
Maturity Level : 5 | Normative | Compartments : N/A |
Normative Candidate Note: This page is candidate normative content for R4 in the Conformance Package . Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.
The definition of a value set is used to create a simple collection of codes suitable for use for data entry or validation.
If the operation is not called at the instance level, one of the in parameters url, context or valueSet must be provided. An expanded value set will be returned, or an OperationOutcome with an error message.
The official URL for this operation definition is
http://hl7.org/fhir/OperationDefinition/ValueSet-expand
Formal Definition (as a OperationDefinition ).
URL: [base]/ValueSet/$expand
URL: [base]/ValueSet/[id]/$expand
This is an idempotent operation
| In Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| url | 0..1 | uri |
A canonical url for a value set. The server must know the value set (e.g. it is defined explicitly in the server's value sets, or it is defined implicitly by some code system known to the server |
||
| valueSet | 0..1 | ValueSet |
The value set is provided directly as part of the request. Servers may choose not to accept value sets in this fashion |
||
| valueSetVersion | 0..1 | string |
The identifier that is used to identify a specific version of the value set to be used when generating the expansion. This is an arbitrary value managed by the value set author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. |
||
| context | 0..1 | uri |
The
context
of
the
value
set,
so
that
the
server
can
resolve
this
to
a
value
set
to
expand.
The
recommended
format
for
this
URI
is
[Structure
Definition
URL]#[name
or
path
into
structure
definition]
e.g.
http://hl7.org/fhir/StructureDefinition/observation-hspc-height-hspcheight#Observation.interpretation.
Other
forms
may
be
used
but
are
not
defined.
This
form
is
only
usable
if
the
terminology
server
also
has
access
to
the
|
||
|
|
0..1 |
|
|
||
|
|
0..1 |
|
A
Text Search engines such as Lucene or Solr, long with their considerable functionality, might also be used. The optional text search might also be code system specific, and servers might have different implementations for different code systems |
||
| date | 0..1 | dateTime |
The date for which the expansion should be generated. if a date is provided, it means that the server should use the value set / code system definitions as they were on the given date, or return an error if this is not possible. Normally, the date is the current conditions (which is the default value) but under some circumstances, systems need to generate an expansion as it would have been in the past. A typical example of this would be where code selection is constrained to the set of codes that were available when the patient was treated, not when the record is being edited. Note that which date is appropriate is a matter for implementation policy. |
||
| offset | 0..1 | integer |
Paging support - where to start if a subset is desired (default = 0). Offset is number of records (not number of pages) |
||
| count | 0..1 | integer |
Paging support - how many codes should be provided in a partial page view. Paging only applies to flat expansions - servers ignore paging if the expansion is not flat. If count = 0, the client is asking how large the expansion is. Servers SHOULD honor this request for hierarchical expansions as well, and simply return the overall count |
||
| includeDesignations | 0..1 | boolean |
Controls
whether
concept
designations
are
to
be
included
or
excluded
in
value
set
| ||
| designation | 0..* | string |
A
token
that
specifies
a
system+code
that
is
either
a
use
or
a
language.
Designations
that
match
by
language
or
use
are
included
in
the
|
||
| includeDefinition | 0..1 | boolean |
Controls
whether
the
value
set
definition
is
included
or
excluded
in
value
set
|
||
| activeOnly | 0..1 | boolean |
Controls
whether
inactive
concepts
are
included
or
excluded
in
value
set
expansions.
|
||
| excludeNested | 0..1 | boolean |
Controls
whether
or
not
the
value
set
expansion
nests
codes
or
not
(i.e.
|
||
| excludeNotForUI | 0..1 | boolean |
Controls
whether
or
not
the
value
set
expansion
|
||
| excludePostCoordinated | 0..1 | boolean |
Controls
whether
or
not
the
value
set
expansion
includes
post
coordinated
|
||
| displayLanguage | 0..1 | code |
Specifies
the
language
to
be
used
for
description
in
the
expansions
i.e.
the
language
to
be
used
for
| ||
| exclude-system | 0..* | canonical |
Code
system,
or
a
particular
version
of
a
code
system
to
be
excluded
from
the
value
|
||
|
|
|
|
| ||
| check-system-version | 0..* | canonical |
Edge
Case:
Specifies
a
version
to
| ||
| force-system-version | 0..* | canonical |
Edge
Case:
Specifies
a
version
to
use
|
||
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| return | 1..1 | ValueSet |
The result of the expansion. Servers generating expansions SHOULD ensure that all the parameters that affect the contents of the expansion are recorded in the ValueSet.expansion.parameter list Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource |
||
The value set expansion returned by this query should be treated as a transient result that will change over time (whether it does or not depends on how the value set is specified), so applications should repeat the operation each time the value set is used.
If
the
expansion
is
too
large
(at
the
discretion
of
the
server),
the
server
will
MAY
return
an
error
(OperationOutcome
with
code
too-costly).
Clients
can
work
through
large
flat
expansions
in
a
set
of
pages
(partial
views
of
the
full
expansion)
instead
of
just
getting
the
full
expansion
in
a
single
exchange
by
using
offset
and
count
parameters.
parameters,
or
use
the
count
parameter
to
request
a
subset
of
the
expansion
for
limited
purposes.
Servers
are
not
obliged
to
support
paging,
but
if
they
do,
SHALL
support
both
the
offset
and
count
parameters.
Hierarchical
expansions
are
not
subject
to
paging
and
servers
simply
return
the
entire
expansion.
Different servers may return different results from expanding a value set for the following reasons:
When a server cannot correctly expand a value set because it does not fully understand the code systems (e.g. it has the wrong version, or incomplete definitions) then it SHALL return an error. If the value set itself is unbounded due to the inclusion of post-coordinated value sets (e.g. SNOMED CT, UCUM), then the extension http://hl7.org/fhir/StructureDefinition/valueset-unclosed can be used to indicate that the expansion is incomplete
Expanding a value set that is already registered on the server as "23", with a text filter of "abdo" (Request):
GET [base]/ValueSet/23/$expand?filter=abdo
Expanding a value set that is specififed by the client (using JSON) (Request):
POST [base]/ValueSet/23/$expand
[other headers]
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "valueSet",
"resource" : {
"resourceType" : "ValueSet",
[value set details]
}
}
]
}
Response:
HTTP/1.1 200 OK
[other headers]
<ValueSet xmlns="http://hl7.org/fhir">
<!-- the server SHOULD populate the id with a newly created UUID
so clients can easily track a particular expansion -->
<id value="43770626-f685-4ba8-8d66-fb63e674c467"/>
<!-- no need for meta, though it is allowed for security labels, profiles -->
<!-- other value set details -->
<expansion>
<!-- when expanded -->
<timestamp value="20141203T08:50:00+11:00"/>
<contains>
<!-- expansion contents -->
</contains>
</expansion>
</ValueSet>
For more information about operations, including how they are invoked, see Operations .
®©
HL7.org
2011+.
FHIR
Mixed
Nomative/Trial
Use
Ballot
(v3.3.0-13671)
#2
(v3.5.0-14907)
generated
on
Tue,
Apr
3,
Sun,
Aug
19,
2018
12:10+1000.
21:51+1000.
QA
Page
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
|
Compare
to
DSTU3
|
Ballot
Comparison
|
|
Propose
a
change