This
page
is
part
of
FHIR
STU
3
(v3.0.1)
in
it's
permanent
home
(it
will
always
be
available
at
this
URL).
It
has
been
superceded
by
R4
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.

5.4
5.5
Resource
OperationDefinition
-
Content

This
page
has
been
approved
as
part
of
an
ANSI
standard.
See
the
Conformance
Package
for
further
details.

A
formal
computable
definition
of
an
operation
(on
the
RESTful
interface)
or
a
named
query
(using
the
search
interaction).

5.4.1
5.5.1
Scope
and
Usage

The
OperationDefinition
resource
provides
a
formal
computable
definition
of
an
operation
or
a
named
query
.
The
OperationDefinition
serves
two
principal
purposes:

To
allow
for
automatic
determination
of
system
compatibility

To
allow
for
dynamic
generation
of
forms
to
drive
the
operations

See
below
for
further
information
about
these,
and
about
how
operations
and
named
queries
are
executed.

5.4.2
5.5.2
Boundaries
and
Relationships

OperationDefinitions
are
published
to
define
operations
that
servers
can
implement
in
a
common
fashion.
The
FHIR
specification
itself
describes
some
(see
below),
and
other
organizations
(including
IHE,
national
programs,
jurisdictions
and
vendors)
are
able
to
publish
additional
OperationDefinitions.

OperationDefinition
resources
are
referred
to
from
two
different
places:

From
another
OperationDefinition
resource.
This
allows
for
a
server
to
describe
a
limited
implementation
of
a
standard
operation,
or
to
allow
traceability
if
the
server
has
to
rename
the
operation
due
to
a
name
clash

Parameters
for
the
operation/query
+
Rule:
Either
a
type
must
be
provided,
or
parts
+
Rule:
A
search
type
can
only
be
specified
for
parameters
of
type
string
+
Rule:
A
targetProfile
can
only
be
specified
for
parameters
of
type
Reference
or
Canonical

Change
value
set
from
http://hl7.org/fhir/ValueSet/conformance-resource-status
to
http://hl7.org/fhir/ValueSet/publication-status
OperationDefinition.experimental
Now
marked
as
Modifier
OperationDefinition.contact
Type
changed
from
BackboneElement
http://hl7.org/fhir/ValueSet/publication-status|4.0.0
to
ContactDetail
http://hl7.org/fhir/ValueSet/publication-status|4.1.0

Parameters
for
the
operation/query
+
Rule:
Either
a
type
must
be
provided,
or
parts
+
Rule:
A
search
type
can
only
be
specified
for
parameters
of
type
string
+
Rule:
A
targetProfile
can
only
be
specified
for
parameters
of
type
Reference
or
Canonical

Change
value
set
from
http://hl7.org/fhir/ValueSet/conformance-resource-status
to
http://hl7.org/fhir/ValueSet/publication-status
OperationDefinition.experimental
Now
marked
as
Modifier
OperationDefinition.contact
Type
changed
from
BackboneElement
http://hl7.org/fhir/ValueSet/publication-status|4.0.0
to
ContactDetail
http://hl7.org/fhir/ValueSet/publication-status|4.1.0

5.5.4.4
Describing
Operation
Parameters

There
are
2
ways
to
describe
the
input
and
output
parameters
for
an
operation:

Using
OperationDefinition.parameter
to
describe
the
parameters

Using
OperationDefinition.inputProfile
and
OperationDefinition.outputProfile

The
parameters
is
a
simple
list
of
possible
parameters,
along
with
cardinalities
and
types.
The
profiles
allow
a
rich
set
of
validation
rules
etc.
to
be
provided.
OperationDefinitions
SHALL
always
define
the
parameters
using
OperationDefinition.parameter
in
the
resource,
and
MAY
also
provide
profiles
for
the
parameters.
If
present,
the
profiles
SHALL
NOT
disagree
with
the
parameters
defined
for
the
operation.

As
an
example,
consider
an
operation
that
defines
3
parameters,
2
in
and
1
out:

This
profile
would
describe
a
parameters
resource
with
2
parameters
(using
slicing),
with
the
same
details
as
the
table
above.
The
operation
definition
would
still
list
the
parameters
directly
to
save
applications
consuming
the
definition
(e.g.
to
produce
an
OpenAPI
document
5.4.3.4
)
from
parsing
and
interpreting
the
profile.

5.5.4.5
Executing
Operations
and
Named
Queries

Operations
OperationDefinitions
with
kind
=
operation
are
executed
by
POSTing
to
a
URL
that
is
as
defined
by
in
the
operation
definition
Operations
Framework
.

5.5.4.6
Executing
Named
Queries

Named
queries
(OperationDefinitions
with
kind
=
query
)
are
executed
by
performing
a
search
with
the
value
of
the
search
parameter
"_query"
set
to
the
name
provided
in
the
definition.

If
the
named
query
is
to
be
performed
over
the
RESTful
API,
all
the
parameters
must
be
simple
search
parameters,
so
that
they
can
be
represented
directly
in
the
URL
without
tricky
encoding
issues.
Named
queries
always
return
a
bundle
containing
a
set
of
resources,
so
all
the
out
parameters
must
be
resources,
not
data
types.

For
named
queries,
all
the
standard
search
parameters
are
automatically
in
scope
(though
servers
do
not
need
to
support
them
unless
explicitly
documented).

5.5.4.7
Passing
Resources
to
Operations

There
are
two
ways
to
pass
resources
to
an
operation:
directly
or
by
reference.
The
definition
of
an
operation
distinguishes
between
these
two,
since
they
have
very
different
behaviors
and
consequences.

As
an
example,
take
the
Questionnaire.$populate
ValueSet.$expand
operation
.
This
operation
takes
a
questionnaire
valueset
as
a
direct
parameter.
The
type
of
the
parameter
is
defined
as
'Questionnaire'.
'ValueSet'.
In
a
Parameters
resource,
it
would
be
represented
like
this:

Other
parameters
are
passed
by
reference.
For
example,
$populate
the
ChargeItemDefinition.$apply
operation
takes
a
set
two
parameters
of
references
to
other
resources
that
should
be
used
type
Reference
-
one
to
pre-populate
the
questionnaire.
These
are
passed
by
reference,
chargeItem
and
the
other
to
the
account.
The
type
of
the
parameter
parameters
is
Reference(Any)
Reference(Charge)
-
a
reference
to
any
kind
and
Reference(Account)
,
respectively.
The
expectation
is
that
the
server
performing
the
operation
will
resolve
those
references
as
part
of
resource.
the
operation
execution.
In
a
parameters
resource,
it
the
chargeItem
parameter
would
be
represented
like
this:

5.5.4.8
Renaming
OperationDefinition.name

It
is
possible
for
two
different
organizations
to
create
different
operation
definitions
with
the
same
name
or,
perhaps
more
likely,
to
define
equivalent
operations
that
have
the
same
name
but
incompatible
approaches
in
their
parameter
lists.

It
is
also
possible,
though
unlikely,
that
a
server
will
be
required
to
support
both
of
these
operations.
If
this
is
the
case,
the
server
is
able
to
do
this
by
giving
one
of
them
a
new
name
and
referring
to
it
by
definition
in
the
capability
statement.
To
illustrate
this,
assume
that
two
different
organizations,
"orgA"
and
"orgB",
both
define
an
operation
called
"dothis",
and
the
definitions
are
incompatible.
OrgA
publishes
its
operation
definition
at
http://orga.com/fhir/dothis.xml,
and
OrgB
publishes
its
operation
at
http://fhir.orgb.com/meta/OperationDefinition/dothis.
The
server
is
able
to
implement
both.
Its
capability
statement
will
say:

If
a
general
purpose
cross
server
client
is
looking
for
the
implementation
of
the
http://fhir.orgb.com/meta/OperationDefinition/dothis
operation
and
wants
to
be
robust
against
this
name
clash
problem,
instead
of
simply
executing
the
$dothis
operation,
it
can
look
at
the
server's
CapabilityStatement
for
the
underlying
definition
URI
and
then
execute
the
name
given
in
the
capability
statement.

5.5.4.9
Determining
System
Compatibility

A
client
can
determine
the
compatibility
of
the
server
by
processing
its
capability
statement
and
ensuring
that
the
server
implements
the
specific
operation
definitions
and
parameters
required
by
the
client.
The
client
can
then
report
a
useful
error
to
the
user
rather
than
allowing
mystifying
operational
errors
to
occur.

However,
there
are
fundamental
limitations
to
this
approach
because
there
are
many
aspects
of
these
operations
that
are
not
(or
cannot
be)
defined
in
a
formal
fashion
using
OperationDefinition,
for
example,
co-occurrence
constraints
among
parameters.

In
the
same
sense,
a
3rd
party
tool
can
examine
a
server's
CapabilityStatement
and
a
client's
definition
of
an
acceptable
server
to
determine
whether
those
two
system
are
interoperable
or
not.

5.5.4.10
Dynamically
Generating
Forms

Finally,
it
is
possible
to
generate
user
interface
forms
automatically
from
the
OperationDefinition.
The
documentation
in
the
OperationDefinition.description
and
OperationDefinition.parameter.documentation
should
be
sufficient
to
allow
moderately
technical
users
to
guess
at
the
correct
content
of
the
form.
For
this
reason,
highly
technical
documentation
should
go
in
OperationDefinition.comment
.

It
is
anticipated
that
this
would
be
used
to
automate
development
processes,
rather
than
to
generate
end-user
forms:
such
users
will
usually
need
more
support
than
can
be
offered
in
a
generated
form.

5.4.4
5.5.5
Search
Parameters

Search
parameters
for
this
resource.
The
common
parameters
also
apply.
See
Searching
for
more
information
about
searching
in
REST,
messaging,
and
services.