This
page
is
part
of
the
FHIR
Specification
(v3.0.2:
STU
3).
The
current
version
which
supercedes
this
version
is
5.0.0
.
For
a
full
list
Continuous
Integration
Build
of
available
versions,
see
FHIR
(will
be
incorrect/inconsistent
at
times).
See
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
R3
R2
Responsible
Owner:
FHIR
Infrastructure
Work
Group
|
|
|
Compartments
:
|
A formal computable definition of an operation (on the RESTful interface) or a named query (using the search interaction).
The OperationDefinition resource provides a formal computable definition of an operation or a named query . The OperationDefinition serves two principal purposes:
See below for further information about these, and about how operations and named queries are executed.
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:
OperationDefinitions
can
be
used
to
define
a
custom
query
(kind
=
query,
discussed
below)
which
functions
as
a
special
kind
of
search.
This
resource
is
referenced
by
different
to
a
SearchParameter
because
a
custom
query
may
define
multiple
parameters
and
can
define
of
complex
search
behavior
beyond
what
SearchParameter
can
specify.
It
also
typically
overrides
the
behavior
of
the
query
functionality,
while
search
parameters
can
only
act
as
additional
filters.
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
||||
|---|---|---|---|---|---|---|---|---|
|
N | DomainResource |
Definition
of
an
operation
or
a
named
query
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation + Rule: A query operation cannot be defined at the instance level + Rule: A query operation requires input parameters to have a search type + Rule: Named queries always have a single output parameter named 'result' of type Bundle Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension Interfaces Implemented: CanonicalResource |
|||||
|
Σ C | 0..1 | uri |
Canonical
identifier
for
this
operation
+ Warning: URL should not contain | or # - these characters make processing canonical references problematic |
||||
|
Σ | 0..* |
Identifier
|
Additional
identifier
for
the
implementation
guide
(business
identifier)
|
||||
| Σ | 0..1 | string |
Business
version
of
the
operation
definition
|
||||
|
Σ | 0..1 |
How
to
compare
versions
Binding: Version Algorithm ( Extensible ) | |||||
![]() ![]() ![]() |
|
string | ||||||
| Coding | |||||||
![]() ![]() | Σ C | 1..1 | string |
Name
for
this
operation
definition
(computer
friendly)
|
||||
|
Σ T | 0..1 | string |
Name
for
this
operation
definition
(human
friendly)
| ||||
![]() ![]() | ?! Σ | 1..1 | code |
draft
|
active
|
retired
|
unknown
Binding: PublicationStatus ( Required ) |
||||
|
Σ C | 1..1 | code |
operation
|
query
|
||||
|
|
0..1 | boolean |
For
testing
|
||||
|
Σ | 0..1 | dateTime |
Date
|
||||
|
Σ T | 0..1 | string |
Name
of
the
|
||||
|
Σ | 0..* | ContactDetail |
Contact
details
for
the
publisher
|
||||
|
T | 0..1 | markdown |
Natural
language
description
of
the
operation
definition
|
||||
|
Σ | 0..* | UsageContext |
The
context
that
the
content
is
intended
to
support
|
||||
|
Σ | 0..* | CodeableConcept |
Jurisdiction
of
the
authority
that
maintains
the
operation
definition
(if
applicable)
Binding: Jurisdiction ValueSet
(
Extensible
)
|
||||
|
T | 0..1 | markdown |
Why
this
operation
definition
is
defined
|
||||
|
T
|
0..1 | markdown |
Notice
about
intellectual
property
ownership,
can
include
restrictions
on
use
|
||||
| T | 0..1 | string |
Copyright
holder
and
year(s)
| ||||
![]() ![]() | Σ | 0..1 | boolean |
Whether
content
is
|
||||
| Σ | 0..1 | code |
synchronous
|
asynchronous
|
either
Binding: Operation Synchronicity Control ( Required ) |
||||
|
Σ | 1..1 | code |
Recommended
name
for
operation
in
search
url
|
||||
|
0..1 |
|
Additional
information
about
use
|
|||||
|
Σ | 0..1 |
|
Marks
this
as
a
profile
of
the
base
|
||||
|
Σ | 0..* | code |
Types
this
operation
applies
to
|
||||
|
Σ | 1..1 | boolean |
Invoke
at
the
system
level?
|
||||
|
Σ | 1..1 | boolean |
Invoke
at
the
type
level?
|
||||
|
Σ C | 1..1 | boolean |
Invoke
on
an
instance?
|
||||
|
0..1 |
|
Validation
information
for
in
parameters
|
|||||
|
0..1 |
|
Validation
information
for
out
parameters
|
|||||
| C | 0..* | BackboneElement |
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, Canonical, or a Resource + Rule: SearchParamType can only be specified on in parameters + Rule: Min <= Max |
||||
|
C | 1..1 | code |
Name
in
Parameters.parameter.name
or
in
URL
|
||||
|
C | 1..1 | code |
in
|
out
Binding: Operation Parameter Use ( Required ) |
||||
| 0..* | code |
instance
|
type
|
system
Binding: Operation Parameter Scope ( Required ) |
|||||
|
1..1 |
|
Minimum
Cardinality
|
|||||
|
C | 1..1 | string |
Maximum
Cardinality
(a
number
or
*)
+ Rule: Max SHALL be a number or "*" |
||||
|
T | 0..1 |
|
Description
of
meaning/use
|
||||
|
|
0..1 | code |
What
type
this
parameter
has
|
||||
|
0..* | code |
Allowed
sub-type
this
parameter
can
have
(if
type
is
abstract)
|
|||||
|
C
|
0..* |
|
If
type
is
Reference
|
canonical,
allowed
targets.
If
type
is
'Resource',
then
this
constrains
the
allowed
resource
types
|
||||
|
C | 0..1 |
code
|
number
|
date
|
string
|
token
|
reference
|
composite
|
quantity
|
uri
|
special
|
resource
Binding: SearchParamType ( Required ) |
||||
| 0..1 | BackboneElement |
ValueSet
details
if
this
is
coded
|
|||||
|
1..1 | code |
required
|
extensible
|
preferred
|
example
|
descriptive
Binding: BindingStrength ( Required ) |
|||||
|
1..1 | canonical ( ValueSet ) |
Source
of
value
set
|
|||||
|
0..* | BackboneElement |
References
to
this
parameter
|
|||||
|
1..1 | string |
Referencing
parameter
|
|||||
|
0..1 |
|
Element
id
of
reference
|
|||||
|
|
0..* | see parameter |
Parts
of
a
nested
Parameter
|
||||
|
0..* | BackboneElement |
Define
overloaded
variants
for
when
generating
code
|
|||||
|
0..* | string |
Name
of
parameter
to
include
in
overload
|
|||||
|
0..1 | string |
Comments
to
go
on
overload
|
|||||
Documentation
for
this
format
|
||||||||
See the Extensions for this resource
UML Diagram ( Legend )
XML Template
<<OperationDefinition xmlns="http://hl7.org/fhir"><!-- from Resource: id, meta, implicitRules, and language --> <!-- from DomainResource: text, contained, extension, and modifierExtension -->
< < < < < < < <<url value="[uri]"/><!-- 0..1 Canonical identifier for this operation definition, represented as an absolute URI (globally unique) --> <identifier><!-- 0..* Identifier Additional identifier for the implementation guide (business identifier) --></identifier> <version value="[string]"/><!-- 0..1 Business version of the operation definition --> <versionAlgorithm[x]><!-- 0..1 string|Coding How to compare versions --></versionAlgorithm[x]> <name value="[string]"/><!-- I 1..1 Name for this operation definition (computer friendly) --> <title value="[string]"/><!-- 0..1 Name for this operation definition (human friendly) --> <status value="[code]"/><!-- 1..1 draft | active | retired | unknown --> <kind value="[code]"/><!-- I 1..1 operation | query --> <experimental value="[boolean]"/><!-- 0..1 For testing only - never for real usage --> <date value="[dateTime]"/><!-- 0..1 Date last changed --> <publisher value="[string]"/><!-- 0..1 Name of the publisher/steward (organization or individual) --> <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>< <</useContext> <</jurisdiction> < < < < <</base> < < < < < < < < < < < < <</profile><description value="[markdown]"/><!-- 0..1 Natural language description of the operation definition --> <useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext> <jurisdiction><!-- 0..* CodeableConcept Jurisdiction of the authority that maintains the operation definition (if applicable)--></jurisdiction> <purpose value="[markdown]"/><!-- 0..1 Why this operation definition is defined --> <copyright value="[markdown]"/><!-- 0..1 Notice about intellectual property ownership, can include restrictions on use --> <copyrightLabel value="[string]"/><!-- 0..1 Copyright holder and year(s) --> <affectsState value="[boolean]"/><!-- 0..1 Whether content is changed by the operation --> <synchronicity value="[code]"/><!-- 0..1 synchronous | asynchronous | either --> <code value="[code]"/><!-- 1..1 Recommended name for operation in search url --> <comment value="[markdown]"/><!-- 0..1 Additional information about use --> <base><!-- 0..1 canonical(OperationDefinition) Marks this as a profile of the base --></base> <resource value="[code]"/><!-- 0..* Types this operation applies to --> <system value="[boolean]"/><!-- 1..1 Invoke at the system level? --> <type value="[boolean]"/><!-- 1..1 Invoke at the type level? --> <instance value="[boolean]"/><!-- I 1..1 Invoke on an instance? --> <inputProfile><!-- 0..1 canonical(StructureDefinition) Validation information for in parameters --></inputProfile> <outputProfile><!-- 0..1 canonical(StructureDefinition) Validation information for out parameters --></outputProfile> <parameter> <!-- I 0..* Parameters for the operation/query --> <name value="[code]"/><!-- I 1..1 Name in Parameters.parameter.name or in URL --> <use value="[code]"/><!-- I 1..1 in | out --> <scope value="[code]"/><!-- 0..* instance | type | system --> <min value="[unsignedInt]"/><!-- 1..1 Minimum Cardinality --> <max value="[string]"/><!-- 1..1 Maximum Cardinality (a number or *) --> <documentation value="[markdown]"/><!-- 0..1 Description of meaning/use --> <type value="[code]"/><!-- I 0..1 What type this parameter has --> <allowedType value="[code]"/><!-- 0..* Allowed sub-type this parameter can have (if type is abstract) --> <targetProfile><!-- I 0..* canonical(StructureDefinition) If type is Reference | canonical, allowed targets. If type is 'Resource', then this constrains the allowed resource types --></targetProfile> <searchType value="[code]"/><!-- I 0..1 number | date | string | token | reference | composite | quantity | uri | special | resource --> <binding> <!-- 0..1 ValueSet details if this is coded -->
< <</valueSet[x]><strength value="[code]"/><!-- 1..1 required | extensible | preferred | example | descriptive --> <valueSet><!-- 1..1 canonical(ValueSet) Source of value set --></valueSet> </binding><</part><referencedFrom> <!-- 0..* References to this parameter --> <source value="[string]"/><!-- 1..1 Referencing parameter --> <sourceId value="[string]"/><!-- 0..1 Element id of reference --> </referencedFrom> <part><!-- I 0..* Content as for OperationDefinition.parameter Parts of a nested Parameter --></part> </parameter> <overload> <!-- 0..* Define overloaded variants for when generating code -->< <<parameterName value="[string]"/><!-- 0..* Name of parameter to include in overload --> <comment value="[string]"/><!-- 0..1 Comments to go on overload --> </overload> </OperationDefinition>
JSON Template
{
"resourceType" : "",
"resourceType" : "OperationDefinition",
// from Resource: id, meta, implicitRules, and language
// from DomainResource: text, contained, extension, and modifierExtension
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
">"
" }
"url" : "<uri>", // Canonical identifier for this operation definition, represented as an absolute URI (globally unique)
"identifier" : [{ Identifier }], // Additional identifier for the implementation guide (business identifier)
"version" : "<string>", // Business version of the operation definition
// versionAlgorithm[x]: How to compare versions. One of these 2:
"versionAlgorithmString" : "<string>",
"versionAlgorithmCoding" : { Coding },
"name" : "<string>", // I R! Name for this operation definition (computer friendly)
"title" : "<string>", // Name for this operation definition (human friendly)
"status" : "<code>", // R! draft | active | retired | unknown
"kind" : "<code>", // I R! operation | query
"experimental" : <boolean>, // For testing only - never for real usage
"date" : "<dateTime>", // Date last changed
"publisher" : "<string>", // Name of the publisher/steward (organization or individual)
"contact" : [{ ContactDetail }], // Contact details for the publisher
"description" : "<markdown>", // Natural language description of the operation definition
"useContext" : [{ UsageContext }], // The context that the content is intended to support
"jurisdiction" : [{ CodeableConcept }], // Jurisdiction of the authority that maintains the operation definition (if applicable)
"purpose" : "<markdown>", // Why this operation definition is defined
"copyright" : "<markdown>", // Notice about intellectual property ownership, can include restrictions on use
"copyrightLabel" : "<string>", // Copyright holder and year(s)
"affectsState" : <boolean>, // Whether content is changed by the operation
"synchronicity" : "<code>", // synchronous | asynchronous | either
"code" : "<code>", // R! Recommended name for operation in search url
"comment" : "<markdown>", // Additional information about use
"base" : "<canonical(OperationDefinition)>", // Marks this as a profile of the base
"resource" : ["<code>"], // Types this operation applies to
"system" : <boolean>, // R! Invoke at the system level?
"type" : <boolean>, // R! Invoke at the type level?
"instance" : <boolean>, // I R! Invoke on an instance?
"inputProfile" : "<canonical(StructureDefinition)>", // Validation information for in parameters
"outputProfile" : "<canonical(StructureDefinition)>", // Validation information for out parameters
"parameter" : [{ // I Parameters for the operation/query
"name" : "<code>", // I R! Name in Parameters.parameter.name or in URL
"use" : "<code>", // I R! in | out
"scope" : ["<code>"], // instance | type | system
"min" : "<unsignedInt>", // R! Minimum Cardinality
"max" : "<string>", // R! Maximum Cardinality (a number or *)
"documentation" : "<markdown>", // Description of meaning/use
"type" : "<code>", // I What type this parameter has
"allowedType" : ["<code>"], // Allowed sub-type this parameter can have (if type is abstract)
"targetProfile" : ["<canonical(StructureDefinition)>"], // I If type is Reference | canonical, allowed targets. If type is 'Resource', then this constrains the allowed resource types
"searchType" : "<code>", // I number | date | string | token | reference | composite | quantity | uri | special | resource
"binding" : { // ValueSet details if this is coded
"strength" : "<code>", // R! required | extensible | preferred | example | descriptive
"valueSet" : "<canonical(ValueSet)>" // R! Source of value set
},
"
"referencedFrom" : [{ // References to this parameter
"source" : "<string>", // R! Referencing parameter
"sourceId" : "<string>" // Element id of reference
}],
"part" : [{ Content as for OperationDefinition.parameter }] // I Parts of a nested Parameter
}],
"
"
"
"overload" : [{ // Define overloaded variants for when generating code
"parameterName" : ["<string>"], // Name of parameter to include in overload
"comment" : "<string>" // Comments to go on overload
}]
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> .[ a fhir:OperationDefinition; fhir:nodeRole fhir:treeRoot; # if this is the parser root
# from # from fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: # . One of these 2 fhir: ] fhir:) ] ]; fhir: ], ...; fhir: fhir: fhir: ], ...;# from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir:modifierExtension fhir:url [ uri ] ; # 0..1 Canonical identifier for this operation definition, represented as an absolute URI (globally unique) fhir:identifier ( [ Identifier ] ... ) ; # 0..* Additional identifier for the implementation guide (business identifier) fhir:version [ string ] ; # 0..1 Business version of the operation definition # versionAlgorithm[x] : 0..1 How to compare versions. One of these 2 fhir:versionAlgorithm [ a fhir:String ; string ] fhir:versionAlgorithm [ a fhir:Coding ; Coding ] fhir:name [ string ] ; # 1..1 I Name for this operation definition (computer friendly) fhir:title [ string ] ; # 0..1 Name for this operation definition (human friendly) fhir:status [ code ] ; # 1..1 draft | active | retired | unknown fhir:kind [ code ] ; # 1..1 I operation | query fhir:experimental [ boolean ] ; # 0..1 For testing only - never for real usage fhir:date [ dateTime ] ; # 0..1 Date last changed fhir:publisher [ string ] ; # 0..1 Name of the publisher/steward (organization or individual) fhir:contact ( [ ContactDetail ] ... ) ; # 0..* Contact details for the publisher fhir:description [ markdown ] ; # 0..1 Natural language description of the operation definition fhir:useContext ( [ UsageContext ] ... ) ; # 0..* The context that the content is intended to support fhir:jurisdiction ( [ CodeableConcept ] ... ) ; # 0..* Jurisdiction of the authority that maintains the operation definition (if applicable) fhir:purpose [ markdown ] ; # 0..1 Why this operation definition is defined fhir:copyright [ markdown ] ; # 0..1 Notice about intellectual property ownership, can include restrictions on use fhir:copyrightLabel [ string ] ; # 0..1 Copyright holder and year(s) fhir:affectsState [ boolean ] ; # 0..1 Whether content is changed by the operation fhir:synchronicity [ code ] ; # 0..1 synchronous | asynchronous | either fhir:code [ code ] ; # 1..1 Recommended name for operation in search url fhir:comment [ markdown ] ; # 0..1 Additional information about use fhir:base [ canonical(OperationDefinition) ] ; # 0..1 Marks this as a profile of the base fhir:resource ( [ code ] ... ) ; # 0..* Types this operation applies to fhir:system [ boolean ] ; # 1..1 Invoke at the system level? fhir:type [ boolean ] ; # 1..1 Invoke at the type level? fhir:instance [ boolean ] ; # 1..1 I Invoke on an instance? fhir:inputProfile [ canonical(StructureDefinition) ] ; # 0..1 Validation information for in parameters fhir:outputProfile [ canonical(StructureDefinition) ] ; # 0..1 Validation information for out parameters fhir:parameter ( [ # 0..* I Parameters for the operation/query fhir:name [ code ] ; # 1..1 I Name in Parameters.parameter.name or in URL fhir:use [ code ] ; # 1..1 I in | out fhir:scope ( [ code ] ... ) ; # 0..* instance | type | system fhir:min [ unsignedInt ] ; # 1..1 Minimum Cardinality fhir:max [ string ] ; # 1..1 Maximum Cardinality (a number or *) fhir:documentation [ markdown ] ; # 0..1 Description of meaning/use fhir:type [ code ] ; # 0..1 I What type this parameter has fhir:allowedType ( [ code ] ... ) ; # 0..* Allowed sub-type this parameter can have (if type is abstract) fhir:targetProfile ( [ canonical(StructureDefinition) ] ... ) ; # 0..* I If type is Reference | canonical, allowed targets. If type is 'Resource', then this constrains the allowed resource types fhir:searchType [ code ] ; # 0..1 I number | date | string | token | reference | composite | quantity | uri | special | resource fhir:binding [ # 0..1 ValueSet details if this is coded fhir:strength [ code ] ; # 1..1 required | extensible | preferred | example | descriptive fhir:valueSet [ canonical(ValueSet) ] ; # 1..1 Source of value set ] ; fhir:referencedFrom ( [ # 0..* References to this parameter fhir:source [ string ] ; # 1..1 Referencing parameter fhir:sourceId [ string ] ; # 0..1 Element id of reference ] ... ) ; fhir:part ( [ See OperationDefinition.parameter ] ... ) ; # 0..* I Parts of a nested Parameter ] ... ) ; fhir:overload ( [ # 0..* Define overloaded variants for when generating code fhir:parameterName ( [ string ] ... ) ; # 0..* Name of parameter to include in overload fhir:comment [ string ] ; # 0..1 Comments to go on overload ] ... ) ; ]
Changes
since
DSTU2
from
both
R4
and
R4B
| OperationDefinition | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| OperationDefinition.parameter.type |
|
|
|
|
|
|
|
|
|
|
See the Full Difference for further information
This
analysis
is
available
for
R4
as
XML
or
JSON
.
See
R2
<-->
R3
Conversion
Maps
(status
=
18
tests
that
all
execute
ok.
1
fail
round-trip
testing
and
all
r3
resources
are
valid.).
for
R4B
as
XML
or
JSON
.
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
||||
|---|---|---|---|---|---|---|---|---|
|
N | DomainResource |
Definition
of
an
operation
or
a
named
query
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation + Rule: A query operation cannot be defined at the instance level + Rule: A query operation requires input parameters to have a search type + Rule: Named queries always have a single output parameter named 'result' of type Bundle Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension Interfaces Implemented: CanonicalResource |
|||||
|
Σ C | 0..1 | uri |
Canonical
identifier
for
this
operation
+ Warning: URL should not contain | or # - these characters make processing canonical references problematic |
||||
|
Σ | 0..* | Identifier |
Additional
identifier
for
the
implementation
guide
(business
identifier)
|
||||
| Σ | 0..1 | string |
Business
version
of
the
operation
definition
|
||||
|
Σ | 0..1 |
How
to
compare
versions
Binding: Version Algorithm ( Extensible ) | |||||
![]() ![]() ![]() |
|
string | ||||||
| Coding | |||||||
![]() ![]() | Σ C | 1..1 | string |
Name
for
this
operation
definition
(computer
friendly)
|
||||
|
Σ T | 0..1 | string |
Name
for
this
operation
definition
(human
friendly)
| ||||
![]() ![]() | ?! Σ | 1..1 | code |
draft
|
active
|
retired
|
unknown
Binding: PublicationStatus ( Required ) |
||||
|
Σ C | 1..1 | code |
operation
|
query
|
||||
|
|
0..1 | boolean |
For
testing
|
||||
|
Σ | 0..1 | dateTime |
Date
|
||||
|
Σ T | 0..1 | string |
Name
of
the
|
||||
|
Σ | 0..* | ContactDetail |
Contact
details
for
the
publisher
|
||||
|
T | 0..1 | markdown |
Natural
language
description
of
the
operation
definition
|
||||
|
Σ | 0..* | UsageContext |
The
context
that
the
content
is
intended
to
support
|
||||
|
Σ | 0..* | CodeableConcept |
Jurisdiction
of
the
authority
that
maintains
the
operation
definition
(if
applicable)
Binding: Jurisdiction ValueSet
(
Extensible
)
|
||||
|
T | 0..1 | markdown |
Why
this
operation
definition
is
defined
|
||||
|
T
|
0..1 | markdown |
Notice
about
intellectual
property
ownership,
can
include
restrictions
on
use
|
||||
| T | 0..1 | string |
Copyright
holder
and
year(s)
| ||||
![]() ![]() | Σ | 0..1 | boolean |
Whether
content
is
|
||||
| Σ | 0..1 | code |
synchronous
|
asynchronous
|
either
Binding: Operation Synchronicity Control ( Required ) |
||||
|
Σ | 1..1 | code |
Recommended
name
for
operation
in
search
url
|
||||
|
0..1 |
|
Additional
information
about
use
|
|||||
|
Σ | 0..1 |
|
Marks
this
as
a
profile
of
the
base
|
||||
|
Σ | 0..* | code |
Types
this
operation
applies
to
|
||||
|
Σ | 1..1 | boolean |
Invoke
at
the
system
level?
|
||||
|
Σ | 1..1 | boolean |
Invoke
at
the
type
level?
|
||||
|
Σ C | 1..1 | boolean |
Invoke
on
an
instance?
|
||||
|
0..1 |
|
Validation
information
for
in
parameters
|
|||||
|
0..1 |
|
Validation
information
for
out
parameters
|
|||||
| C | 0..* | BackboneElement |
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, Canonical, or a Resource + Rule: SearchParamType can only be specified on in parameters + Rule: Min <= Max |
||||
|
C | 1..1 | code |
Name
in
Parameters.parameter.name
or
in
URL
|
||||
|
C | 1..1 | code |
in
|
out
Binding: Operation Parameter Use ( Required ) |
||||
| 0..* | code |
instance
|
type
|
system
Binding: Operation Parameter Scope ( Required ) |
|||||
|
1..1 |
|
Minimum
Cardinality
|
|||||
|
C | 1..1 | string |
Maximum
Cardinality
(a
number
or
*)
+ Rule: Max SHALL be a number or "*" |
||||
|
T | 0..1 |
|
Description
of
meaning/use
|
||||
|
|
0..1 | code |
What
type
this
parameter
has
|
||||
|
0..* | code |
Allowed
sub-type
this
parameter
can
have
(if
type
is
abstract)
|
|||||
|
C
|
0..* |
|
If
type
is
Reference
|
canonical,
allowed
targets.
If
type
is
'Resource',
then
this
constrains
the
allowed
resource
types
|
||||
|
C | 0..1 |
code
|
number
|
date
|
string
|
token
|
reference
|
composite
|
quantity
|
uri
|
special
|
resource
Binding: SearchParamType ( Required ) |
||||
| 0..1 | BackboneElement |
ValueSet
details
if
this
is
coded
|
|||||
|
1..1 | code |
required
|
extensible
|
preferred
|
example
|
descriptive
Binding: BindingStrength ( Required ) |
|||||
|
1..1 | canonical ( ValueSet ) |
Source
of
value
set
|
|||||
|
0..* | BackboneElement |
References
to
this
parameter
|
|||||
|
1..1 | string |
Referencing
parameter
|
|||||
|
0..1 |
|
Element
id
of
reference
|
|||||
|
|
0..* | see parameter |
Parts
of
a
nested
Parameter
|
||||
|
0..* | BackboneElement |
Define
overloaded
variants
for
when
generating
code
|
|||||
|
0..* | string |
Name
of
parameter
to
include
in
overload
|
|||||
|
0..1 | string |
Comments
to
go
on
overload
|
|||||
Documentation
for
this
format
|
||||||||
See the Extensions for this resource
XML Template
<<OperationDefinition xmlns="http://hl7.org/fhir"><!-- from Resource: id, meta, implicitRules, and language --> <!-- from DomainResource: text, contained, extension, and modifierExtension -->
< < < < < < < <<url value="[uri]"/><!-- 0..1 Canonical identifier for this operation definition, represented as an absolute URI (globally unique) --> <identifier><!-- 0..* Identifier Additional identifier for the implementation guide (business identifier) --></identifier> <version value="[string]"/><!-- 0..1 Business version of the operation definition --> <versionAlgorithm[x]><!-- 0..1 string|Coding How to compare versions --></versionAlgorithm[x]> <name value="[string]"/><!-- I 1..1 Name for this operation definition (computer friendly) --> <title value="[string]"/><!-- 0..1 Name for this operation definition (human friendly) --> <status value="[code]"/><!-- 1..1 draft | active | retired | unknown --> <kind value="[code]"/><!-- I 1..1 operation | query --> <experimental value="[boolean]"/><!-- 0..1 For testing only - never for real usage --> <date value="[dateTime]"/><!-- 0..1 Date last changed --> <publisher value="[string]"/><!-- 0..1 Name of the publisher/steward (organization or individual) --> <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>< <</useContext> <</jurisdiction> < < < < <</base> < < < < < < < < < < < < <</profile><description value="[markdown]"/><!-- 0..1 Natural language description of the operation definition --> <useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext> <jurisdiction><!-- 0..* CodeableConcept Jurisdiction of the authority that maintains the operation definition (if applicable)--></jurisdiction> <purpose value="[markdown]"/><!-- 0..1 Why this operation definition is defined --> <copyright value="[markdown]"/><!-- 0..1 Notice about intellectual property ownership, can include restrictions on use --> <copyrightLabel value="[string]"/><!-- 0..1 Copyright holder and year(s) --> <affectsState value="[boolean]"/><!-- 0..1 Whether content is changed by the operation --> <synchronicity value="[code]"/><!-- 0..1 synchronous | asynchronous | either --> <code value="[code]"/><!-- 1..1 Recommended name for operation in search url --> <comment value="[markdown]"/><!-- 0..1 Additional information about use --> <base><!-- 0..1 canonical(OperationDefinition) Marks this as a profile of the base --></base> <resource value="[code]"/><!-- 0..* Types this operation applies to --> <system value="[boolean]"/><!-- 1..1 Invoke at the system level? --> <type value="[boolean]"/><!-- 1..1 Invoke at the type level? --> <instance value="[boolean]"/><!-- I 1..1 Invoke on an instance? --> <inputProfile><!-- 0..1 canonical(StructureDefinition) Validation information for in parameters --></inputProfile> <outputProfile><!-- 0..1 canonical(StructureDefinition) Validation information for out parameters --></outputProfile> <parameter> <!-- I 0..* Parameters for the operation/query --> <name value="[code]"/><!-- I 1..1 Name in Parameters.parameter.name or in URL --> <use value="[code]"/><!-- I 1..1 in | out --> <scope value="[code]"/><!-- 0..* instance | type | system --> <min value="[unsignedInt]"/><!-- 1..1 Minimum Cardinality --> <max value="[string]"/><!-- 1..1 Maximum Cardinality (a number or *) --> <documentation value="[markdown]"/><!-- 0..1 Description of meaning/use --> <type value="[code]"/><!-- I 0..1 What type this parameter has --> <allowedType value="[code]"/><!-- 0..* Allowed sub-type this parameter can have (if type is abstract) --> <targetProfile><!-- I 0..* canonical(StructureDefinition) If type is Reference | canonical, allowed targets. If type is 'Resource', then this constrains the allowed resource types --></targetProfile> <searchType value="[code]"/><!-- I 0..1 number | date | string | token | reference | composite | quantity | uri | special | resource --> <binding> <!-- 0..1 ValueSet details if this is coded -->
< <</valueSet[x]><strength value="[code]"/><!-- 1..1 required | extensible | preferred | example | descriptive --> <valueSet><!-- 1..1 canonical(ValueSet) Source of value set --></valueSet> </binding><</part><referencedFrom> <!-- 0..* References to this parameter --> <source value="[string]"/><!-- 1..1 Referencing parameter --> <sourceId value="[string]"/><!-- 0..1 Element id of reference --> </referencedFrom> <part><!-- I 0..* Content as for OperationDefinition.parameter Parts of a nested Parameter --></part> </parameter> <overload> <!-- 0..* Define overloaded variants for when generating code -->< <<parameterName value="[string]"/><!-- 0..* Name of parameter to include in overload --> <comment value="[string]"/><!-- 0..1 Comments to go on overload --> </overload> </OperationDefinition>
JSON Template
{
"resourceType" : "",
"resourceType" : "OperationDefinition",
// from Resource: id, meta, implicitRules, and language
// from DomainResource: text, contained, extension, and modifierExtension
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
"
">"
" }
"url" : "<uri>", // Canonical identifier for this operation definition, represented as an absolute URI (globally unique)
"identifier" : [{ Identifier }], // Additional identifier for the implementation guide (business identifier)
"version" : "<string>", // Business version of the operation definition
// versionAlgorithm[x]: How to compare versions. One of these 2:
"versionAlgorithmString" : "<string>",
"versionAlgorithmCoding" : { Coding },
"name" : "<string>", // I R! Name for this operation definition (computer friendly)
"title" : "<string>", // Name for this operation definition (human friendly)
"status" : "<code>", // R! draft | active | retired | unknown
"kind" : "<code>", // I R! operation | query
"experimental" : <boolean>, // For testing only - never for real usage
"date" : "<dateTime>", // Date last changed
"publisher" : "<string>", // Name of the publisher/steward (organization or individual)
"contact" : [{ ContactDetail }], // Contact details for the publisher
"description" : "<markdown>", // Natural language description of the operation definition
"useContext" : [{ UsageContext }], // The context that the content is intended to support
"jurisdiction" : [{ CodeableConcept }], // Jurisdiction of the authority that maintains the operation definition (if applicable)
"purpose" : "<markdown>", // Why this operation definition is defined
"copyright" : "<markdown>", // Notice about intellectual property ownership, can include restrictions on use
"copyrightLabel" : "<string>", // Copyright holder and year(s)
"affectsState" : <boolean>, // Whether content is changed by the operation
"synchronicity" : "<code>", // synchronous | asynchronous | either
"code" : "<code>", // R! Recommended name for operation in search url
"comment" : "<markdown>", // Additional information about use
"base" : "<canonical(OperationDefinition)>", // Marks this as a profile of the base
"resource" : ["<code>"], // Types this operation applies to
"system" : <boolean>, // R! Invoke at the system level?
"type" : <boolean>, // R! Invoke at the type level?
"instance" : <boolean>, // I R! Invoke on an instance?
"inputProfile" : "<canonical(StructureDefinition)>", // Validation information for in parameters
"outputProfile" : "<canonical(StructureDefinition)>", // Validation information for out parameters
"parameter" : [{ // I Parameters for the operation/query
"name" : "<code>", // I R! Name in Parameters.parameter.name or in URL
"use" : "<code>", // I R! in | out
"scope" : ["<code>"], // instance | type | system
"min" : "<unsignedInt>", // R! Minimum Cardinality
"max" : "<string>", // R! Maximum Cardinality (a number or *)
"documentation" : "<markdown>", // Description of meaning/use
"type" : "<code>", // I What type this parameter has
"allowedType" : ["<code>"], // Allowed sub-type this parameter can have (if type is abstract)
"targetProfile" : ["<canonical(StructureDefinition)>"], // I If type is Reference | canonical, allowed targets. If type is 'Resource', then this constrains the allowed resource types
"searchType" : "<code>", // I number | date | string | token | reference | composite | quantity | uri | special | resource
"binding" : { // ValueSet details if this is coded
"strength" : "<code>", // R! required | extensible | preferred | example | descriptive
"valueSet" : "<canonical(ValueSet)>" // R! Source of value set
},
"
"referencedFrom" : [{ // References to this parameter
"source" : "<string>", // R! Referencing parameter
"sourceId" : "<string>" // Element id of reference
}],
"part" : [{ Content as for OperationDefinition.parameter }] // I Parts of a nested Parameter
}],
"
"
"
"overload" : [{ // Define overloaded variants for when generating code
"parameterName" : ["<string>"], // Name of parameter to include in overload
"comment" : "<string>" // Comments to go on overload
}]
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> .[ a fhir:OperationDefinition; fhir:nodeRole fhir:treeRoot; # if this is the parser root
# from # from fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: # . One of these 2 fhir: ] fhir:) ] ]; fhir: ], ...; fhir: fhir: fhir: ], ...;# from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir:modifierExtension fhir:url [ uri ] ; # 0..1 Canonical identifier for this operation definition, represented as an absolute URI (globally unique) fhir:identifier ( [ Identifier ] ... ) ; # 0..* Additional identifier for the implementation guide (business identifier) fhir:version [ string ] ; # 0..1 Business version of the operation definition # versionAlgorithm[x] : 0..1 How to compare versions. One of these 2 fhir:versionAlgorithm [ a fhir:String ; string ] fhir:versionAlgorithm [ a fhir:Coding ; Coding ] fhir:name [ string ] ; # 1..1 I Name for this operation definition (computer friendly) fhir:title [ string ] ; # 0..1 Name for this operation definition (human friendly) fhir:status [ code ] ; # 1..1 draft | active | retired | unknown fhir:kind [ code ] ; # 1..1 I operation | query fhir:experimental [ boolean ] ; # 0..1 For testing only - never for real usage fhir:date [ dateTime ] ; # 0..1 Date last changed fhir:publisher [ string ] ; # 0..1 Name of the publisher/steward (organization or individual) fhir:contact ( [ ContactDetail ] ... ) ; # 0..* Contact details for the publisher fhir:description [ markdown ] ; # 0..1 Natural language description of the operation definition fhir:useContext ( [ UsageContext ] ... ) ; # 0..* The context that the content is intended to support fhir:jurisdiction ( [ CodeableConcept ] ... ) ; # 0..* Jurisdiction of the authority that maintains the operation definition (if applicable) fhir:purpose [ markdown ] ; # 0..1 Why this operation definition is defined fhir:copyright [ markdown ] ; # 0..1 Notice about intellectual property ownership, can include restrictions on use fhir:copyrightLabel [ string ] ; # 0..1 Copyright holder and year(s) fhir:affectsState [ boolean ] ; # 0..1 Whether content is changed by the operation fhir:synchronicity [ code ] ; # 0..1 synchronous | asynchronous | either fhir:code [ code ] ; # 1..1 Recommended name for operation in search url fhir:comment [ markdown ] ; # 0..1 Additional information about use fhir:base [ canonical(OperationDefinition) ] ; # 0..1 Marks this as a profile of the base fhir:resource ( [ code ] ... ) ; # 0..* Types this operation applies to fhir:system [ boolean ] ; # 1..1 Invoke at the system level? fhir:type [ boolean ] ; # 1..1 Invoke at the type level? fhir:instance [ boolean ] ; # 1..1 I Invoke on an instance? fhir:inputProfile [ canonical(StructureDefinition) ] ; # 0..1 Validation information for in parameters fhir:outputProfile [ canonical(StructureDefinition) ] ; # 0..1 Validation information for out parameters fhir:parameter ( [ # 0..* I Parameters for the operation/query fhir:name [ code ] ; # 1..1 I Name in Parameters.parameter.name or in URL fhir:use [ code ] ; # 1..1 I in | out fhir:scope ( [ code ] ... ) ; # 0..* instance | type | system fhir:min [ unsignedInt ] ; # 1..1 Minimum Cardinality fhir:max [ string ] ; # 1..1 Maximum Cardinality (a number or *) fhir:documentation [ markdown ] ; # 0..1 Description of meaning/use fhir:type [ code ] ; # 0..1 I What type this parameter has fhir:allowedType ( [ code ] ... ) ; # 0..* Allowed sub-type this parameter can have (if type is abstract) fhir:targetProfile ( [ canonical(StructureDefinition) ] ... ) ; # 0..* I If type is Reference | canonical, allowed targets. If type is 'Resource', then this constrains the allowed resource types fhir:searchType [ code ] ; # 0..1 I number | date | string | token | reference | composite | quantity | uri | special | resource fhir:binding [ # 0..1 ValueSet details if this is coded fhir:strength [ code ] ; # 1..1 required | extensible | preferred | example | descriptive fhir:valueSet [ canonical(ValueSet) ] ; # 1..1 Source of value set ] ; fhir:referencedFrom ( [ # 0..* References to this parameter fhir:source [ string ] ; # 1..1 Referencing parameter fhir:sourceId [ string ] ; # 0..1 Element id of reference ] ... ) ; fhir:part ( [ See OperationDefinition.parameter ] ... ) ; # 0..* I Parts of a nested Parameter ] ... ) ; fhir:overload ( [ # 0..* Define overloaded variants for when generating code fhir:parameterName ( [ string ] ... ) ; # 0..* Name of parameter to include in overload fhir:comment [ string ] ; # 0..1 Comments to go on overload ] ... ) ; ]
Changes
since
DSTU2
from
both
R4
and
R4B
| OperationDefinition | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| OperationDefinition.parameter.type |
|
|
|
|
|
|
|
|
|
|
See the Full Difference for further information
This
analysis
is
available
for
R4
as
XML
or
JSON
.
See
R2
<-->
R3
Conversion
Maps
(status
=
18
tests
that
all
execute
ok.
1
fail
round-trip
testing
and
all
r3
resources
are
valid.).
for
R4B
as
XML
or
JSON
.
Alternate
Additional
definitions:
Master
Definition
(
XML
,
+
JSON
),
,
XML
Schema
/
Schematron
(for
)
+
JSON
Schema
,
ShEx
(for
Turtle
)
,
the
spreadsheet
version
&
the
dependency
analysis
| Path |
|
Type |
|
|---|---|---|---|
| OperationDefinition.versionAlgorithm[x] |
|
|
Indicates the mechanism used to compare versions to determine which is more current. |
| OperationDefinition.status | PublicationStatus | Required | The lifecycle status of an artifact. |
| OperationDefinition.kind | OperationKind | Required |
Whether an operation is a normal operation or a query. |
| OperationDefinition.jurisdiction |
JurisdictionValueSet
|
|
This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used.
Note:
The
codes
for
countries
and
country
subdivisions
are
taken
from
ISO
3166
|
| OperationDefinition.synchronicity |
|
|
Indicates that an operation must always be handled as synchronous or asynchronous, or that the server must provide both, and clients can choose |
| OperationDefinition.resource |
|
Required |
Current and past FHIR resource types (deleted or renamed), including abstract types |
| All Resource Types | ui | ||
| OperationDefinition.parameter.use | OperationParameterUse | Required |
Whether an operation parameter is an input or an output parameter. |
| OperationDefinition.parameter.scope | OperationParameterScope (a valid code from Operation Parameter Use ) | Required |
Indicates that a parameter applies when the operation is being invoked at the specified level |
| OperationDefinition.parameter.type |
|
Required |
All FHIR types |
| OperationDefinition.parameter.allowedType | FHIRTypes (a valid code from All FHIR Types ) | Required |
All FHIR types |
| OperationDefinition.parameter.searchType | SearchParamType | Required |
Data types allowed to be used for search parameters. |
| OperationDefinition.parameter.binding.strength | BindingStrength | Required |
Indication
of
the
degree
of
conformance
expectations
associated
with
a
binding.
|
| UniqueKey |
|
|
|
|
cnl-0
|
Warning | (base) |
Name
should
be
usable
as
an
identifier
for
|
|
cnl-1
|
|
OperationDefinition.url |
| exists() implies matches('^[^|# ]+$') |
opd-1
|
Rule | OperationDefinition.parameter |
Either
a
|
|
opd-2
|
|
OperationDefinition.parameter |
| searchType.exists() implies type = 'string' |
opd-3
| Rule | OperationDefinition.parameter |
| targetProfile.exists() implies (type = 'Reference' or type = 'canonical' or type.memberOf('http://hl7.org/fhir/ValueSet/all-resource-types')) |
opd-4
|
Rule | OperationDefinition.parameter |
SearchParamType
can
only
be
specified
on
|
|
opd-5
|
|
(base) |
| (kind = 'query') implies (instance = false) |
opd-6
|
|
(base) |
| (kind = 'query') implies (parameter.all((use = 'in' and searchType.exists()) or (use != 'in'))) |
opd-7
|
Rule | (base) |
Named
queries
always
have
a
|
|
opd-8
|
|
OperationDefinition.parameter |
| (max = '*') or iif(max != '*', min <= max.toInteger()) |
opd-9
|
|
OperationDefinition.parameter.max |
| empty() or ($this = '*') or (toInteger() >= 0) |
OperationDefinitions can describe entirely new operations, but they can also describe a restricted implementation of an existing operation, e.g. when a server implements some but not all the features of an operation defined in another specification. These are called derived operation definitions.
An OperationDefinition does by declaring a base as shown in the example :
{
"resourceType" : "OperationDefinition",
"id" : "example",
"url" : "http://hl7.org/fhir/OperationDefinition/example",
"name" : "PopulateQuestionnaire",
// snip
"code" : "populate",
"base" : "http://hl7.org/fhir/OperationDefinition/Questionnaire-populate"
// snip
}
When constraining an existing operation like this, operation definitions can make optional parameters required or not used, introduce new parameters (required or optional), clarify documentation, and even change the code for the operation (see next section). The derived operation can't change the nature of the operation itself, nor can it change add types to parameters or prohibit mandatory parameters.
When deriving from another operation, the following rules SHOULD be followed. Note that these rules are asserted as SHOULD rather than SHALL only because they were introduced after the resource became normative. Systems that fail to follow these rules are likely to result in unsafe interoperability.
affectsState
from
the
original
OperationDefinition
kind
as
the
original
OperationDefinition
experimental
as
the
original
OperationDefinition
resource
that
is
equivalent
to
or
a
subset
of
the
original
OperationDefinition
target
system
,
type
,
or
instance
to
'true'
if
they
were
false
in
the
original
OperationDefinition
inputProfile
is
valued,
SHOULD
have
an
inputProfile
valued
such
that:
inputProfile
is
the
same
as,
is
a
profile
of,
or
imposes
the
original
inputProfile
,
or
inputProfile
is
otherwise
compatible
with
the
original
inputProfile
(all
parameters
profiled
with
min
cardinality
1
from
the
original
inputProfile
are
profiled;
all
parameters
profiled
in
the
original
inputProfile
are
profiled
with
equivalent
or
tighter
constraints)
outputProfile
is
valued,
SHOULD
have
an
outputProfile
valued
such
that:
the
original
outputProfile,
or
parameter
with
the
same
name
as
any
parameter
of
the
original
OperationDefinition
that
has
a
parameter.min
value
of
greater
than
zero
parameter
with
the
same
parameter.name
as
a
parameter
of
the
original
OperationDefinition,
use
as
the
original
parameter
min
value
as
the
original
parameter
max
value
as
the
original
parameter
parameter.type
is
valued,
SHOULD
have
the
same
type
as
the
original
parameter
parameter.allowedType
is
valued,
SHOULD
have
an
allowedType
that
is
the
same
or
a
subset
of
the
original
parameter.allowedType
parameter.targetProfile
is
valued,
SHOULD
only
include
targetProfile
that
are
the
same
as,
or
profiles
of,
original
parameter.targetProfile
entries.
It
is
also
possible
to
reduce
the
number
of
allowed
targetProfiles.
parameter.searchType
is
valued,
SHOULD
have
a
searchType
with
the
same
value
as
the
original
parameter.searchType
parameter.binding
is
valued,
SHOULD
have
a
binding
with
the
same
values
as,
or
values
meeting
the
constraints
of,
the
original
parameter.binding
parameter.referencedFrom
is
valued,
SHOULD
have
a
referencedFrom
with
the
same
values.
parameter.part
is
valued,
part
with
the
same
name
as
any
part
of
the
original
OperationDefinition
with
a
min
value
of
greater
than
zero
part
with
the
same
name
as
a
part
of
the
original
OperationDefinition,
SHOULD
meet
the
above
derivation
rules
Request for ballot feedback: We would like the 'SHOULD' assertions above to become 'SHALL' assertions. We are invoking our usual implementer outreach process to find out whether anyone else objects, but please file tickets for any rules you do not believe can be enforced that way.
Operations
are
invoked
by
their
code,
not
their
name.
The
name
is
descriptive,
for
code
generation,
e.g.
ValueSetExpansion
,
while
the
code
is
what
is
used
in
a
URL
e.g.
http://example.org/fhir/ValueSet/$expand
.
When
defining
operations,
for
maximum
compatibility,
use
only
lowercase
ASCII
characters.
See
Naming
Rules
&
Guidelines
[base]/PlanDefinition/[id]/$data-requirements
for
the
internal
HL7
rules
around
codes,
which
are
useful
additional
advice
for
all
implementers.
It is possible for two different organizations to create different operation definitions with the same code or, perhaps more likely, to define equivalent operations that have the same code but incompatible approaches in their parameter lists. Note that HL7 will never define multiple operations with the same code.
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
code
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
with
a
code
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:
<CapabilityStatement xmlns="http://hl7.org/fhir">
<!-- snip -->
<rest>
<!-- snip -->
<operation>
<name value="dothis"/>
<definition>
<reference value="http://orga.com/fhir/dothis.xml"/>
</definition>
</operation>
<operation>
<name value="dothis2"/>
<definition>
<reference value="http://fhir.orgb.com/meta/OperationDefinition/dothis"/>
</definition>
</operation>
<!-- snip -->
</rest>
<!-- snip -->
</CapabilityStatement>
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
with
the
name
given
in
the
capability
statement.
Note to implementers: it would be more consistent if CapabilityStatement.rest.operation.name was actually called "code", since it relates to OperationDefinition.code, but the confusion this can cause wasn't appreciated until the resource was normative.
There are 2 ways to describe the input and output parameters for an operation:
OperationDefinition.parameter
to
describe
the
parameters
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:
|
In
Parameters:
|
|||||
|
|
|
Type |
|
Profile |
|
| a | 0..1 |
|
|
An integer parameter |
|
| b | 0..1 |
|
A patient parameter |
||
|
Out
Parameters:
|
|||||
|
|
|
Type |
|
Profile |
|
| c | 1..1 |
|
|
A result parameter |
|
In addition to specifying the operation parameters directly, an operation definition can also provide a profile:
"inputProfile" : "http://example.org/StructureDefinition/op.x.in.profile"
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
)
from
parsing
and
interpreting
the
profile.
Operations
OperationDefinitions
with
kind
=
operation
are
executed
by
POSTing
to
a
URL
that
is
as
defined
by
in
the
operation
definition
Operations
Framework
.
Named
queries
(OperationDefinitions
with
kind
=
query
)
are
executed
by
performing
a
search
with
the
value
of
the
search
parameter
"_query"
"_query"
set
to
the
name
provided
in
the
definition.
Named
queries
are
a
kind
of
search:
both
client
and
server
must
conform
to
all
the
requirements
of
search,
including
regarding
the
content
of
the
result
bundle.
From
a
client's
perspective,
it's
really
just
a
kind
of
search,
though
it
may
have
a
completely
separate
processing
pipeline.
Named
queries
cannot
be
invoked
using
the
$[operationname]
mechanism.
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
have
a
set
single
output
parameter
named
"result"
of
resources,
so
type
Bundle.
The
order
of
parameters
doesn't
matter;
a
_query
parameter
anywhere
in
the
query
means
the
entire
query
will
be
handled
according
to
the
named
query
OperationDefinition.
Parameters
may
repeat
if
permitted
by
the
OperationDefinition
(or
for
unlisted
common
search
parameters,
as
specified
in
this
specification).
For
named
queries,
all
the
out
standard
search
parameters
are
automatically
in
scope.
Specifically,
all
common
search
parameters
(e.g.
_id,
_text,
_count,
_sort,
etc.)
as
well
as
search
parameters
that
pertain
to
the
resources
returned
by
the
operation
(e.g.
name
for
Patient
or
Organization)
are
allowed.
"In
scope"
doesn't
mean
all
servers
will
support
them.
If
a
server
wishes
to
declare
which
search
parameters
it
supports
for
a
given
named
query,
it
must
explicitly
list
these
in
its
OperationDefinition
(which
might
be
resources,
not
data
types.
a
server-specific
derived
OperationDefinition).
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:
<parameter><name value="questionnaire"/><name value="valueset"/> <resource><Questionnaire> <!-- Questionnaire contents --> </Questionnaire><ValueSet> <!-- ValueSet contents --> </ValueSet> </resource> </parameter>
or, in JSON:
"parameter": ["parameter": [ {"name": "questionnaire", "resource": { "resourceType": "Questionnaire", // Questionnaire contents"name": "valueset", "resource": { "resourceType": "ValueSet", // ValueSet contents } } ]
Other
parameters
are
passed
by
reference.
For
example,
$populate
the
PlanDefinition.$apply
operation
takes
a
set
more
than
one
parameters
of
references
to
other
resources
type
Reference
-
subject,
encounter
and
organization.
The
expectation
is
that
should
be
used
to
pre-populate
the
questionnaire.
These
are
passed
by
reference,
and
server
performing
the
type
operation
will
resolve
those
references
as
part
of
the
parameter
is
Reference(Any)
-
a
reference
to
any
kind
of
resource.
operation
execution.
In
a
parameters
resource,
it
the
subject
parameter
would
be
represented
like
this:
<parameter><name value="content"/><name value="subject"/> <valueReference><reference value="Patient/123"> </Questionnaire><reference value="Patient/123"/> </valueReference> </parameter>
or, in JSON:
"parameter": ["parameter": [ {"name": "questionnaire", "valueReference" : { "reference" : "Patient/123""name": "subject", "valueReference" : { "reference" : "Patient/123" } } ]
Some
operations
can
take
either
form;
in
that
case,
two
distinct
parameters
must
be
defined,
defined:
one
for
a
resource
as
a
direct
parameter,
and
one
for
a
reference.
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.
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.
| Base Operations (All resource types) | |
| Validate a resource | [base]/$validate | [base]/[Resource]/$validate | [base]/[Resource]/[id]/$validate |
| Convert from one form to another | [base]/$convert |
| Execute a graphql statement | [base]/$graphql | [base]/[Resource]/[id]/$graphql |
| Fetch the current version of a canonical resource (based on canonical versioning) | [base]/$current-canonical | [base]/[CanonicalResource]/$current-canonical |
| Operations Defined by Resource Types | |
| Apply | [base]/ActivityDefinition/$apply | [base]/ActivityDefinition/[id]/$apply |
| Data Requirements | [base]/ActivityDefinition/[id]/$data-requirements |
| Discover what versions a server supports | [base]/$versions |
| Submit a Claim resource for adjudication | [base]/Claim/$submit |
| Concept Look Up & Decomposition | [base]/CodeSystem/$lookup | [base]/CodeSystem/[id]/$lookup |
| Code System based Validation | [base]/CodeSystem/$validate-code | [base]/CodeSystem/[id]/$validate-code |
| Subsumption Testing | [base]/CodeSystem/$subsumes | [base]/CodeSystem/[id]/$subsumes |
| Generate a Document | [base]/Composition/[id]/$document |
| Concept Translation | [base]/ConceptMap/$translate | [base]/ConceptMap/[id]/$translate |
| Submit an EligibilityRequest resource for assessment | [base]/CoverageEligibilityRequest/$submit |
| Fetch DocumentReference | [base]/DocumentReference/$docref |
| Fetch a group of Patient Records | [base]/Group/[id]/$everything |
| Purge Group Record | [base]/Group/[id]/$purge |
| Data Requirements | [base]/$data-requirements | [base]/Library/[id]/$data-requirements |
| Evaluate | [base]/Measure/$evaluate |
| Evaluate Measure | [base]/Measure/$evaluate-measure | [base]/Measure/[id]/$evaluate-measure |
| Data Requirements | [base]/Measure/[id]/$data-requirements |
| Submit Data | [base]/Measure/$submit-data |
| Collect Data | [base]/Measure/$collect-data |
| Care Gaps | [base]/Measure/$care-gaps |
| Fetch Product Record | [base]/MedicinalProductDefinition/$everything | [base]/MedicinalProductDefinition/[id]/$everything |
| Process Message | [base]/$process-message |
| Fetch Preferred id | [base]/NamingSystem/$preferred-id |
| Translate id | [base]/NamingSystem/$translate-id |
| Observation Statistics | [base]/Observation/$stats |
| Last N Observations Query | [base]/Observation/$lastn |
| Find patient matches using MPI based logic | [base]/Patient/$match |
| Purge Patient Record | [base]/Patient/[id]/$purge |
| Apply | [base]/PlanDefinition/$apply | [base]/PlanDefinition/[id]/$apply |
| Data Requirements | [base]/PlanDefinition/[id]/$data-requirements |
| Generate Snapshot | [base]/StructureDefinition/$snapshot | [base]/StructureDefinition/[id]/$snapshot |
| Model Instance Transformation | [base]/StructureMap/$transform | [base]/StructureMap/[id]/$transform |
| Search and retrieve prior events for a Subscription | [base]/Subscription/[id]/$events |
| Get Current Subscription Status for One or More Subscriptions | [base]/Subscription/$status | [base]/Subscription/[id]/$status |
| Value Set Expansion | [base]/ValueSet/$expand | [base]/ValueSet/[id]/$expand |
| Value Set based Validation | [base]/ValueSet/$validate-code | [base]/ValueSet/[id]/$validate-code |
Search parameters for this resource. See also the full list of search parameters for this resource , and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.
| Name | Type | Description | Expression | In Common |
| base | reference | Marks this as a profile of the base |
OperationDefinition.base
( OperationDefinition ) |
|
| code | token | Name used to invoke the operation | OperationDefinition.code | |
| context | token | A use context assigned to the operation definition | (OperationDefinition.useContext.value.ofType(CodeableConcept)) | 24 Resources |
| context-quantity | quantity | A quantity- or range-valued use context assigned to the operation definition | (OperationDefinition.useContext.value.ofType(Quantity)) | (OperationDefinition.useContext.value.ofType(Range)) | 24 Resources |
| context-type | token | A type of use context assigned to the operation definition | OperationDefinition.useContext.code | 24 Resources |
| context-type-quantity | composite | A use context type and quantity- or range-based value assigned to the operation definition |
On
OperationDefinition.useContext:
context-type: code context-quantity: value.ofType(Quantity) | value.ofType(Range) | 24 Resources |
| context-type-value | composite | A use context type and value assigned to the operation definition |
On
OperationDefinition.useContext:
context-type: code context: value.ofType(CodeableConcept) | 24 Resources |
| date | date | The operation definition publication date | OperationDefinition.date | 25 Resources |
| description | string | The description of the operation definition | OperationDefinition.description | 23 Resources |
| experimental |
token
|
Whether the OperationDefinition is experimental | OperationDefinition.experimental | |
| identifier | token | External identifier for the search parameter | OperationDefinition.identifier | 28 Resources |
| input-profile | reference | Validation information for in parameters |
OperationDefinition.inputProfile
( StructureDefinition ) | |
| instance | token | Invoke on an instance? | OperationDefinition.instance | |
| jurisdiction | token |
|
OperationDefinition.jurisdiction | 21 Resources |
| kind | token | operation | query | OperationDefinition.kind | |
| name | string | Computationally friendly name of the operation definition | OperationDefinition.name | 23 Resources |
|
output-profile
|
reference |
|
( StructureDefinition ) |
|
| publisher | string | Name of the publisher of the operation definition | OperationDefinition.publisher | 25 Resources |
| status | token | The current status of the operation definition | OperationDefinition.status | 28 Resources |
| system | token | Invoke at the system level? | OperationDefinition.system | |
| title | string | The human-friendly name of the operation definition | OperationDefinition.title | 23 Resources |
| type | token |
|
OperationDefinition.type | |
| url | uri | The uri that identifies the operation definition | OperationDefinition.url | 29 Resources |
| version | token | The business version of the operation definition | OperationDefinition.version | 26 Resources |