5.4 Resource OperationDefinition - Content

PublicationStatus

OperationDefinition.kind

Whether an operation is a normal operation or a query.

OperationKind

OperationDefinition.jurisdiction

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 icon while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) icon .

Extensible

Jurisdiction ValueSet

OperationDefinition.resource

All fhir data types

ResourceType

OperationDefinition.parameter.use

Whether an operation parameter is an input or an output parameter.

OperationParameterUse

OperationDefinition.parameter.scope

Indicates that a parameter applies when the operation is being invoked at the specified level

OperationParameterScope

OperationDefinition.parameter.type

All FHIR types

FHIRTypes

OperationDefinition.parameter.allowedType

All FHIR types

FHIRTypes

OperationDefinition.parameter.searchType

Data types allowed to be used for search parameters.

SearchParamType

OperationDefinition.parameter.binding.strength

Indication of the degree of conformance expectations associated with a binding.

BindingStrength

5.4.4.2 Constraints

UniqueKey

Level

Location

Description

Expression

cnl-0

Warning

(base)

Name should be usable as an identifier for the module by machine processing applications such as code generation

name.exists() implies name.matches('[A-Z]([A-Za-z0-9_]){1,254}')

cnl-1

Warning

OperationDefinition.url

URL should not contain | or # - these characters make processing canonical references problematic

url.matches('([^|#])*')

opd-1

OperationDefinition.parameter

Either a type must be provided, or parts

type.exists() or part.exists()

opd-2

OperationDefinition.parameter

A search type can only be specified for parameters of type string

searchType.exists() implies type = 'string'

opd-3

OperationDefinition.parameter

A targetProfile can only be specified for parameters of type Reference or Canonical

targetProfile.exists() implies (type = 'Reference' or type = 'canonical')

opd-4

OperationDefinition.parameter

SearchParamType can only be specified on in parameters

(use = 'out') implies searchType.empty()

opd-5

(base)

A query operation cannot be defined at the instance level

(kind = 'query') implies (instance = false)

opd-6

Access a list of profiles, tags, and security labels

(base)

A query operation requires input parameters to have a search type

(kind = 'query') implies (parameter.all((use = 'in' and searchType.exists()) or (use != 'in')))

5.4.4.3 OperationDefinition Code

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 icon 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.

5.4.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:

In Parameters:

Name

Cardinality

Type

Binding

Profile

Documentation

0..1

integer

An integer parameter

0..1

Patient

A patient parameter

Out Parameters:

Name

Cardinality

Type

Binding

Profile

Documentation

1..1

decimal

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 icon ) from parsing and interpreting the profile.

5.4.4.5 Executing Operations

OperationDefinitions with kind = operation are executed as defined in the Operations Framework.

5.4.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.4.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 ValueSet.$expand operation. This operation takes a valueset as a direct parameter. The type of the parameter is defined as 'ValueSet'. In a Parameters resource, it would be represented like this:

  <parameter>
    <name value="valueset"/>
    <resource>
      <ValueSet>
        <!-- Valueset contents -->
      </ValueSet>
    </resource>
  </parameter>

or, in JSON:

 "parameter": [
    {
      "name": "valueset",
      "resource": {
        "resourceType": "ValueSet",
        // Valueset contents 
      }
    }
  ]

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

  <parameter>
    <name value="chargeItem"/>
    <valueReference>
      <reference value="ChargeItem/123"/>
    </valueReference>
  </parameter>

or, in JSON:

 "parameter": [
    {
      "name": "chargeItem",
      "valueReference" : {
        "reference" : "ChargeItem/123"
      }
    }
  ]

Some operations can take either form; in that case, two distinct parameters must be defined: one for a resource as a direct parameter, and one for a reference.

5.4.4.8 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.4.4.9 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.10 Operations defined as part of this Specification

Base Operations (All resource types)

Validate a resource

[base]/[Resource]/$validate | [base]/[Resource]/[id]/$validate

[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

Convert from one form to another

[base]/$convert

Execute a graphql statement

[base]/$graphql | [base]/[Resource]/[id]/$graphql

Return a graph of resources

[base]/[Resource]/[id]/$graph

Add to an array in a large resource

[base]/[Resource]/[id]/$add

Remove from an array in a large resource

[base]/[Resource]/[id]/$remove

Filter an array in a large resource

[base]/[Resource]/[id]/$filter

Operations Defined by Resource Types

[base]/ActivityDefinition/$apply | [base]/ActivityDefinition/[id]/$apply

Fetch a subset of the CapabilityStatement resource

[base]/ActivityDefinition/[id]/$data-requirements

[base]/CapabilityStatement/$subset | [base]/CapabilityStatement/[id]/$subset

Test if a server implements a client's required operations

[base]/CapabilityStatement/$implements | [base]/CapabilityStatement/[id]/$implements

Test if a server implements a client's required operations

[base]/CapabilityStatement/$conforms

Discover what versions a server supports

[base]/$versions

Submit a Claim resource for adjudication

[base]/ChargeItemDefinition/[id]/$apply

[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

Finding codes based on supplied properties

[base]/CodeSystem/$find-matches | [base]/CodeSystem/[id]/$find-matches

Generate a Document

[base]/Composition/$document | [base]/Composition/[id]/$document

Concept Translation

[base]/ConceptMap/$translate | [base]/ConceptMap/[id]/$translate

Closure Table Maintenance

[base]/$closure

Submit an EligibilityRequest resource for assessment

[base]/CoverageEligibilityRequest/$submit

Generate a DocumentReference from a document

[base]/DocumentReference/$generate

Fetch Encounter Record

[base]/Encounter/[id]/$everything

Fetch a group of Patient Records

[base]/Group/[id]/$everything

[base]/$data-requirements | [base]/Library/[id]/$data-requirements

Find a functional list

[base]/List/$find

Evaluate Measure

[base]/Measure/$evaluate-measure | [base]/Measure/[id]/$evaluate-measure

Last N Observations Query

[base]/Measure/[id]/$data-requirements

Submit Data

[base]/Measure/$submit-data | [base]/Measure/[id]/$submit-data

Collect Data

[base]/Measure/$collect-data | [base]/Measure/[id]/$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

[base]/Observation/$lastn

Find patient matches using MPI based logic

[base]/Patient/$match

Fetch Patient Record

[base]/Patient/$everything | [base]/Patient/[id]/$everything

Patient Merge

[base]/Patient/$merge

[base]/PlanDefinition/$apply | [base]/PlanDefinition/[id]/$apply

[base]/PlanDefinition/[id]/$data-requirements