This page is part of the FHIR Specification (v1.2.0: STU 3 Draft). 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 R3 R2

• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles

6.18 Resource OperationDefinition - Content

FHIR Infrastructure Work Group

Maturity Level: 1

Compartments: Not linked to any defined compartments

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

This resource is referenced by conformance

6.18.3 Resource Content

 

Alternate definitions: Schema/Schematron, Resource Profile (XML, JSON), Questionnaire

6.18.3.1 Terminology Bindings

Path	Definition	Type	Reference
OperationDefinition.status	The lifecycle status of a Value Set or Concept Map.	Required	ConformanceResourceStatus
OperationDefinition.kind	Whether an operation is a normal operation or a query.	Required	OperationKind
OperationDefinition.type	One of the resource types defined as part of FHIR.	Required	http://hl7.org/fhir/valueset/resource-typesResourceType
OperationDefinition.parameter.use	Whether an operation parameter is an input or an output parameter.	Required	OperationParameterUse
OperationDefinition.parameter.type	The type of a parameter.	Required	Parameter Types used in Operation Definitions
OperationDefinition.parameter.binding.strength	Indication of the degree of conformance expectations associated with a binding.	Required	BindingStrength

6.18.3.2 Constraints

• opd-1: On OperationDefinition.parameter: Either a type must be provided, or parts (xpath on f:OperationDefinition/f:parameter: exists(f:type) or exists(f:part))

6.18.3.3 Operations defined as part of this Specification

Base Operations (All resource types)
Validate a resource	[base]/[Resource]/$validate | [base]/[Resource]/[id]/$validate
Access a list of profiles, tags, and security labels	[base]/$meta | [base]/[Resource]/$meta | [base]/[Resource]/[id]/$meta
Add profiles, tags, and security labels to a resource	[base]/[Resource]/[id]/$meta-add
Delete profiles, tags, and security labels for a resource	[base]/[Resource]/[id]/$meta-delete
Operations Defined by Resource Types
Generate a Document	[base]/Composition/$document
Concept Translation	[base]/ConceptMap/$translate | [base]/ConceptMap/[id]/$translate
Closure Table Maintenance	[base]/$closure
Evaluate	[base]/DecisionSupportRule/[id]/$evaluate
Evaluate	[base]/DecisionSupportServiceModule/[id]/$evaluate
Fetch Encounter Record	[base]/Encounter/[id]/$everything
Find a functional list	[base]/List/$find
Process Message	[base]/$process-message
Fetch Patient Record	[base]/Patient/$everything | [base]/Patient/[id]/$everything
Populate Questionnaire	[base]/Questionnaire/$populate | [base]/Questionnaire/[id]/$populate
Build Questionnaire	[base]/StructureDefinition/$questionnaire | [base]/StructureDefinition/[id]/$questionnaire
Value Set Expansion	[base]/ValueSet/$expand | [base]/ValueSet/[id]/$expand
Concept Look Up	[base]/ValueSet/$lookup
Value Set based Validation	[base]/ValueSet/$validate-code | [base]/ValueSet/[id]/$validate-code
Operations Defined by Implementation Guides

6.18.3.4 Executing Operations and Named Queries

Operations are executed by POSTing to a URL that is defined by the operation definition. Named Queries 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 etc.

6.18.3.5 Passing Resources to Operations

There are two ways to pass resources to an operation - directly, or by reference. Since the two forms havevery different behaviors and consequences, the definition of an Operation distinguishes between these two.

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

  <parameter>
    <name value="questionnaire"/>
    <resource>
      <Questionnaire>
        <!-- Questionnaire contents -->
      </Questionnaire>
    </resource>
  </parameter> 

or, in JSON:

 "parameter": [
    {
      "name": "questionnaire",
      "resource": {
        "resourceType": "Questionnaire",
        // Questionnaire contents 
      }
    }
  ]

Other parameters are passed by reference. For example, populate takes a set of references to other resources that should be used to pre-populate the questionnaire. These are passed by reference, and the type of the parameter is 'Reference(Any)' - a reference to any kind of resource. In a parameters resource, it would be represented like this:

  <parameter>
    <name value="content"/>
    <valueReference>
      <reference value="Patient/123">
      </Questionnaire>
    </valueReference>
  </parameter> 

or, in JSON:

 "parameter": [
    {
      "name": "questionnaire",
      "valueReference" : {
        "reference" : "Patient/123"
      }
    }
  ]

Some operations can take either form; in that case, two different parameters must be defined, one for a resource directly, and one for a reference.

6.18.3.6 Renaming OperationDefinition.name

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

It's also possible, though unlikely, that a server will be required to support both of these operations. Should this be the case, the server is able to do this by giving one of them a new name, and then referring to it by definition in the conformance statement. To illustrate this, let's 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 conformance statement will say:

<Conformance 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 -->
</Conformance>

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 conformance statement for the underlying definition URI, and then execute the name given in the conformance statement.

6.18.3.7 Determining System Compatibility

A client can determine the compatibility of the server by iterating its conformance statement and seeing whether any of the operations it declares to support source from the same definitions as those the client depends on, and whether the server supports the parameters it uses. A client that does this can report a useful error to the user rather than allowing mystifying operational errors to occur.

Note, however, that there are fundamental limitations to this approach because there are many aspects of these operations that aren't (and can't be) defined in a formal fashion. (For example, co-occurrence constraints amongst parameters.)

In the same sense, a 3rd party tool can examine the conformance statements from a server and a client definition of an acceptable server and confirm whether those two system are would be unable to interoperate.

6.18.3.8 Dynamically Generating Forms

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

Note also this is not expected to be a tool of use to typical healthcare end-users; such users will usually need more support than can be offered in a generated form.

6.18.4 Search Parameters

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

Name	Type	Description	Paths
base	reference	Marks this as a profile of the base	OperationDefinition.base (OperationDefinition)
code	token	Name used to invoke the operation	OperationDefinition.code
date	date	Date for this version of the operation definition	OperationDefinition.date
instance	token	Invoke on an instance?	OperationDefinition.instance
kind	token	operation | query	OperationDefinition.kind
name	string	Informal name for this operation	OperationDefinition.name
profile	reference	Profile on the type	OperationDefinition.parameter.profile (StructureDefinition)
publisher	string	Name of the publisher (Organization or individual)	OperationDefinition.publisher
status	token	draft | active | retired	OperationDefinition.status
system	token	Invoke at the system level?	OperationDefinition.system
type	token	Invoke at resource level for these type	OperationDefinition.type
url	uri	Logical URL to reference this operation definition	OperationDefinition.url
version	token	Logical id for this version of the operation definition	OperationDefinition.version