STU 3 Ballot

This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). 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

5.6 Resource OperationDefinition - Content

FHIR Infrastructure Work GroupMaturity Level: 1Compartments: 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).

5.6.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.6.2 Boundaries and Relationships

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

OperationDefinition resources are referred to from two different places:

  • From a Conformance Statement, to declare what operations a system does or should implement
  • 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

This resource is referenced by conformance

5.6.3 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. OperationDefinition DomainResourceDefinition of an operation or a named query
... url 0..1uriLogical URL to reference this operation definition
... version 0..1stringLogical id for this version of the operation definition
... name 1..1stringInformal name for this operation
... status ?!Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... kind 1..1codeoperation | query
OperationKind (Required)
... experimental 0..1booleanIf for testing purposes, not real usage
... date 0..1dateTimeDate for this version of the operation definition
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description 0..1markdownNatural language description of the operation
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1markdownWhy this resource has been created
... idempotent 0..1booleanWhether content is unchanged by the operation
... code 1..1codeName used to invoke the operation
... comment 0..1stringAdditional information about use
... base 0..1Reference(OperationDefinition)Marks this as a profile of the base
... system 1..1booleanInvoke at the system level?
... type 0..*codeInvoke at resource level for these type
ResourceType (Required)
... instance 1..1booleanInvoke on an instance?
... parameter I0..*BackboneElementParameters for the operation/query
Either a type must be provided, or parts
A search type can only be specified for parameters of type string
.... name 1..1codeName in Parameters.parameter.name or in URL
.... use 1..1codein | out
OperationParameterUse (Required)
.... min 1..1integerMinimum Cardinality
.... max 1..1stringMaximum Cardinality (a number or *)
.... documentation 0..1stringDescription of meaning/use
.... type I0..1codeWhat type this parameter has
FHIRAllTypes (Required)
.... searchType I0..1codenumber | date | string | token | reference | composite | quantity | uri
SearchParamType (Required)
.... profile 0..1Reference(StructureDefinition)Profile on the type
.... binding 0..1BackboneElementValueSet details if this is coded
..... strength 1..1coderequired | extensible | preferred | example
BindingStrength (Required)
..... valueSet[x] 1..1Source of value set
...... valueSetUriuri
...... valueSetReferenceReference(ValueSet)
.... part I0..*see parameterParts of a nested Parameter

doco Documentation for this format

UML Diagram (Legend)

OperationDefinition (DomainResource)An absolute URL that is used to identify this operation definition when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this operation definition is (or will be) publishedurl : uri [0..1]The identifier that is used to identify this version of the profile when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the profile author manually and the value should be a timestampversion : string [0..1]A free text natural language name identifying the operationname : string [1..1]The status of the profile (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »Whether this is an operation or a named querykind : code [1..1] « Whether an operation is a normal operation or a query. (Strength=Required)OperationKind! »This profile was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The date this version of the operation definition was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the Operation Definition changesdate : dateTime [0..1]The name of the individual or organization that published the operation definitionpublisher : string [0..1]A free text natural language description of the profile and its usedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of operation definitionsuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »Explains why this operation definition is needed and why it's been constrained as it hasrequirements : markdown [0..1]Operations that are idempotent (see [HTTP specification definition of idempotent](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)) may be invoked by performing an HTTP GET operation instead of a POSTidempotent : boolean [0..1]The name used to invoke the operationcode : code [1..1]Additional information about how to use this operation or named querycomment : string [0..1]Indicates that this operation definition is a constraining profile on the basebase : Reference [0..1] « OperationDefinition »Indicates whether this operation or named query can be invoked at the system level (e.g. without needing to choose a resource type for the context)system : boolean [1..1]Indicates whether this operation or named query can be invoked at the resource type level for any given resource type level (e.g. without needing to choose a resource type for the context)type : code [0..*] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »Indicates whether this operation can be invoked on a particular instance of one of the given typesinstance : boolean [1..1]ContactThe name of an individual to contact regarding the operation definitionname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]ParameterThe name of used to identify the parametername : code [1..1]Whether this is an input or an output parameteruse : code [1..1] « Whether an operation parameter is an input or an output parameter. (Strength=Required)OperationParameterUse! »The minimum number of times this parameter SHALL appear in the request or responsemin : integer [1..1]The maximum number of times this element is permitted to appear in the request or responsemax : string [1..1]Describes the meaning or use of this parameterdocumentation : string [0..1]The type for this parametertype : code [0..1] « Either an abstract type, a resource or a data type. (Strength=Required)FHIRAllTypes! »How the parameter is understood as a search parameter. This is only used if the parameter type is 'string'searchType : code [0..1] « Data types allowed to be used for search parameters. (Strength=Required)SearchParamType! »A profile the specifies the rules that this parameter must conform toprofile : Reference [0..1] « StructureDefinition »BindingIndicates the degree of conformance expectations associated with this binding - that is, the degree to which the provided value set must be adhered to in the instancesstrength : code [1..1] « Indication of the degree of conformance expectations associated with a binding. (Strength=Required)BindingStrength! »Points to the value set or external definition (e.g. implicit value set) that identifies the set of codes to be usedvalueSet[x] : Type [1..1] « uri|Reference(ValueSet) »Contacts to assist a user in finding and communicating with the publishercontact[0..*]Binds to a value set if this parameter is coded (code, Coding, CodeableConcept)binding[0..1]The parts of a nested Parameterpart[0..*]The parameters for the operation/queryparameter[0..*]

XML Template

<OperationDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Logical URL to reference this operation definition -->
 <version value="[string]"/><!-- 0..1 Logical id for this version of the operation definition -->
 <name value="[string]"/><!-- 1..1 Informal name for this operation -->
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <kind value="[code]"/><!-- 1..1 operation | query -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date for this version of the operation definition -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the operation -->
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <requirements value="[markdown]"/><!-- 0..1 Why this resource has been created -->
 <idempotent value="[boolean]"/><!-- 0..1 Whether content is unchanged by the operation -->
 <code value="[code]"/><!-- 1..1 Name used to invoke the operation -->
 <comment value="[string]"/><!-- 0..1 Additional information about use -->
 <base><!-- 0..1 Reference(OperationDefinition) Marks this as a profile of the base --></base>
 <system value="[boolean]"/><!-- 1..1 Invoke at the system level? -->
 <type value="[code]"/><!-- 0..* Invoke at resource level for these type -->
 <instance value="[boolean]"/><!-- 1..1 Invoke on an instance? -->
 <parameter>  <!-- 0..* Parameters for the operation/query -->
  <name value="[code]"/><!-- 1..1 Name in Parameters.parameter.name or in URL -->
  <use value="[code]"/><!-- 1..1 in | out -->
  <min value="[integer]"/><!-- 1..1 Minimum Cardinality -->
  <max value="[string]"/><!-- 1..1 Maximum Cardinality (a number or *) -->
  <documentation value="[string]"/><!-- 0..1 Description of meaning/use -->
  <type value="[code]"/><!-- ?? 0..1 What type this parameter has -->
  <searchType value="[code]"/><!-- ?? 0..1 number | date | string | token | reference | composite | quantity | uri -->
  <profile><!-- 0..1 Reference(StructureDefinition) Profile on the type --></profile>
  <binding>  <!-- 0..1 ValueSet details if this is coded -->
   <strength value="[code]"/><!-- 1..1 required | extensible | preferred | example -->
   <valueSet[x]><!-- 1..1 uri|Reference(ValueSet) Source of value set --></valueSet[x]>
  </binding>
  <part><!-- ?? 0..* Content as for OperationDefinition.parameter Parts of a nested Parameter --></part>
 </parameter>
</OperationDefinition>

JSON Template

{doco
  "resourceType" : "OperationDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Logical URL to reference this operation definition
  "version" : "<string>", // Logical id for this version of the operation definition
  "name" : "<string>", // R!  Informal name for this operation
  "status" : "<code>", // R!  draft | active | retired
  "kind" : "<code>", // R!  operation | query
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date for this version of the operation definition
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<markdown>", // Natural language description of the operation
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<markdown>", // Why this resource has been created
  "idempotent" : <boolean>, // Whether content is unchanged by the operation
  "code" : "<code>", // R!  Name used to invoke the operation
  "comment" : "<string>", // Additional information about use
  "base" : { Reference(OperationDefinition) }, // Marks this as a profile of the base
  "system" : <boolean>, // R!  Invoke at the system level?
  "type" : ["<code>"], // Invoke at resource level for these type
  "instance" : <boolean>, // R!  Invoke on an instance?
  "parameter" : [{ // Parameters for the operation/query
    "name" : "<code>", // R!  Name in Parameters.parameter.name or in URL
    "use" : "<code>", // R!  in | out
    "min" : <integer>, // R!  Minimum Cardinality
    "max" : "<string>", // R!  Maximum Cardinality (a number or *)
    "documentation" : "<string>", // Description of meaning/use
    "type" : "<code>", // C? What type this parameter has
    "searchType" : "<code>", // C? number | date | string | token | reference | composite | quantity | uri
    "profile" : { Reference(StructureDefinition) }, // Profile on the type
    "binding" : { // ValueSet details if this is coded
      "strength" : "<code>", // R!  required | extensible | preferred | example
      // valueSet[x]: Source of value set. One of these 2:
      "valueSetUri" : "<uri>"
      "valueSetReference" : { Reference(ValueSet) }
    },
    "part" : [{ Content as for OperationDefinition.parameter }] // C? Parts of a nested Parameter
  }]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:OperationDefinition;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:OperationDefinition.url [ uri ]; # 0..1 Logical URL to reference this operation definition
  fhir:OperationDefinition.version [ string ]; # 0..1 Logical id for this version of the operation definition
  fhir:OperationDefinition.name [ string ]; # 1..1 Informal name for this operation
  fhir:OperationDefinition.status [ code ]; # 1..1 draft | active | retired
  fhir:OperationDefinition.kind [ code ]; # 1..1 operation | query
  fhir:OperationDefinition.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:OperationDefinition.date [ dateTime ]; # 0..1 Date for this version of the operation definition
  fhir:OperationDefinition.publisher [ string ]; # 0..1 Name of the publisher (Organization or individual)
  fhir:OperationDefinition.contact [ # 0..* Contact details of the publisher
    fhir:OperationDefinition.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:OperationDefinition.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:OperationDefinition.description [ markdown ]; # 0..1 Natural language description of the operation
  fhir:OperationDefinition.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:OperationDefinition.requirements [ markdown ]; # 0..1 Why this resource has been created
  fhir:OperationDefinition.idempotent [ boolean ]; # 0..1 Whether content is unchanged by the operation
  fhir:OperationDefinition.code [ code ]; # 1..1 Name used to invoke the operation
  fhir:OperationDefinition.comment [ string ]; # 0..1 Additional information about use
  fhir:OperationDefinition.base [ Reference(OperationDefinition) ]; # 0..1 Marks this as a profile of the base
  fhir:OperationDefinition.system [ boolean ]; # 1..1 Invoke at the system level?
  fhir:OperationDefinition.type [ code ], ... ; # 0..* Invoke at resource level for these type
  fhir:OperationDefinition.instance [ boolean ]; # 1..1 Invoke on an instance?
  fhir:OperationDefinition.parameter [ # 0..* Parameters for the operation/query
    fhir:OperationDefinition.parameter.name [ code ]; # 1..1 Name in Parameters.parameter.name or in URL
    fhir:OperationDefinition.parameter.use [ code ]; # 1..1 in | out
    fhir:OperationDefinition.parameter.min [ integer ]; # 1..1 Minimum Cardinality
    fhir:OperationDefinition.parameter.max [ string ]; # 1..1 Maximum Cardinality (a number or *)
    fhir:OperationDefinition.parameter.documentation [ string ]; # 0..1 Description of meaning/use
    fhir:OperationDefinition.parameter.type [ code ]; # 0..1 What type this parameter has
    fhir:OperationDefinition.parameter.searchType [ code ]; # 0..1 number | date | string | token | reference | composite | quantity | uri
    fhir:OperationDefinition.parameter.profile [ Reference(StructureDefinition) ]; # 0..1 Profile on the type
    fhir:OperationDefinition.parameter.binding [ # 0..1 ValueSet details if this is coded
      fhir:OperationDefinition.parameter.binding.strength [ code ]; # 1..1 required | extensible | preferred | example
      # OperationDefinition.parameter.binding.valueSet[x] : 1..1 Source of value set. One of these 2
        fhir:OperationDefinition.parameter.binding.valueSetUri [ uri ]
        fhir:OperationDefinition.parameter.binding.valueSetReference [ Reference(ValueSet) ]
    ];
    fhir:OperationDefinition.parameter.part [ See OperationDefinition.parameter ], ... ; # 0..* Parts of a nested Parameter
  ], ...;
]

Changes since DSTU2

OperationDefinition
OperationDefinition.description Type changed from string to markdown
OperationDefinition.useContext added
OperationDefinition.requirements Type changed from string to markdown
OperationDefinition.comment Renamed from notes to comment
OperationDefinition.parameter.type Change value set from http://hl7.org/fhir/ValueSet/operation-parameter-type to http://hl7.org/fhir/ValueSet/all-types
OperationDefinition.parameter.searchType added

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. OperationDefinition DomainResourceDefinition of an operation or a named query
... url 0..1uriLogical URL to reference this operation definition
... version 0..1stringLogical id for this version of the operation definition
... name 1..1stringInformal name for this operation
... status ?!Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... kind 1..1codeoperation | query
OperationKind (Required)
... experimental 0..1booleanIf for testing purposes, not real usage
... date 0..1dateTimeDate for this version of the operation definition
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description 0..1markdownNatural language description of the operation
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1markdownWhy this resource has been created
... idempotent 0..1booleanWhether content is unchanged by the operation
... code 1..1codeName used to invoke the operation
... comment 0..1stringAdditional information about use
... base 0..1Reference(OperationDefinition)Marks this as a profile of the base
... system 1..1booleanInvoke at the system level?
... type 0..*codeInvoke at resource level for these type
ResourceType (Required)
... instance 1..1booleanInvoke on an instance?
... parameter I0..*BackboneElementParameters for the operation/query
Either a type must be provided, or parts
A search type can only be specified for parameters of type string
.... name 1..1codeName in Parameters.parameter.name or in URL
.... use 1..1codein | out
OperationParameterUse (Required)
.... min 1..1integerMinimum Cardinality
.... max 1..1stringMaximum Cardinality (a number or *)
.... documentation 0..1stringDescription of meaning/use
.... type I0..1codeWhat type this parameter has
FHIRAllTypes (Required)
.... searchType I0..1codenumber | date | string | token | reference | composite | quantity | uri
SearchParamType (Required)
.... profile 0..1Reference(StructureDefinition)Profile on the type
.... binding 0..1BackboneElementValueSet details if this is coded
..... strength 1..1coderequired | extensible | preferred | example
BindingStrength (Required)
..... valueSet[x] 1..1Source of value set
...... valueSetUriuri
...... valueSetReferenceReference(ValueSet)
.... part I0..*see parameterParts of a nested Parameter

doco Documentation for this format

UML Diagram (Legend)

OperationDefinition (DomainResource)An absolute URL that is used to identify this operation definition when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this operation definition is (or will be) publishedurl : uri [0..1]The identifier that is used to identify this version of the profile when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the profile author manually and the value should be a timestampversion : string [0..1]A free text natural language name identifying the operationname : string [1..1]The status of the profile (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »Whether this is an operation or a named querykind : code [1..1] « Whether an operation is a normal operation or a query. (Strength=Required)OperationKind! »This profile was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The date this version of the operation definition was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the Operation Definition changesdate : dateTime [0..1]The name of the individual or organization that published the operation definitionpublisher : string [0..1]A free text natural language description of the profile and its usedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of operation definitionsuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »Explains why this operation definition is needed and why it's been constrained as it hasrequirements : markdown [0..1]Operations that are idempotent (see [HTTP specification definition of idempotent](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)) may be invoked by performing an HTTP GET operation instead of a POSTidempotent : boolean [0..1]The name used to invoke the operationcode : code [1..1]Additional information about how to use this operation or named querycomment : string [0..1]Indicates that this operation definition is a constraining profile on the basebase : Reference [0..1] « OperationDefinition »Indicates whether this operation or named query can be invoked at the system level (e.g. without needing to choose a resource type for the context)system : boolean [1..1]Indicates whether this operation or named query can be invoked at the resource type level for any given resource type level (e.g. without needing to choose a resource type for the context)type : code [0..*] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »Indicates whether this operation can be invoked on a particular instance of one of the given typesinstance : boolean [1..1]ContactThe name of an individual to contact regarding the operation definitionname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]ParameterThe name of used to identify the parametername : code [1..1]Whether this is an input or an output parameteruse : code [1..1] « Whether an operation parameter is an input or an output parameter. (Strength=Required)OperationParameterUse! »The minimum number of times this parameter SHALL appear in the request or responsemin : integer [1..1]The maximum number of times this element is permitted to appear in the request or responsemax : string [1..1]Describes the meaning or use of this parameterdocumentation : string [0..1]The type for this parametertype : code [0..1] « Either an abstract type, a resource or a data type. (Strength=Required)FHIRAllTypes! »How the parameter is understood as a search parameter. This is only used if the parameter type is 'string'searchType : code [0..1] « Data types allowed to be used for search parameters. (Strength=Required)SearchParamType! »A profile the specifies the rules that this parameter must conform toprofile : Reference [0..1] « StructureDefinition »BindingIndicates the degree of conformance expectations associated with this binding - that is, the degree to which the provided value set must be adhered to in the instancesstrength : code [1..1] « Indication of the degree of conformance expectations associated with a binding. (Strength=Required)BindingStrength! »Points to the value set or external definition (e.g. implicit value set) that identifies the set of codes to be usedvalueSet[x] : Type [1..1] « uri|Reference(ValueSet) »Contacts to assist a user in finding and communicating with the publishercontact[0..*]Binds to a value set if this parameter is coded (code, Coding, CodeableConcept)binding[0..1]The parts of a nested Parameterpart[0..*]The parameters for the operation/queryparameter[0..*]

XML Template

<OperationDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Logical URL to reference this operation definition -->
 <version value="[string]"/><!-- 0..1 Logical id for this version of the operation definition -->
 <name value="[string]"/><!-- 1..1 Informal name for this operation -->
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <kind value="[code]"/><!-- 1..1 operation | query -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date for this version of the operation definition -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the operation -->
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <requirements value="[markdown]"/><!-- 0..1 Why this resource has been created -->
 <idempotent value="[boolean]"/><!-- 0..1 Whether content is unchanged by the operation -->
 <code value="[code]"/><!-- 1..1 Name used to invoke the operation -->
 <comment value="[string]"/><!-- 0..1 Additional information about use -->
 <base><!-- 0..1 Reference(OperationDefinition) Marks this as a profile of the base --></base>
 <system value="[boolean]"/><!-- 1..1 Invoke at the system level? -->
 <type value="[code]"/><!-- 0..* Invoke at resource level for these type -->
 <instance value="[boolean]"/><!-- 1..1 Invoke on an instance? -->
 <parameter>  <!-- 0..* Parameters for the operation/query -->
  <name value="[code]"/><!-- 1..1 Name in Parameters.parameter.name or in URL -->
  <use value="[code]"/><!-- 1..1 in | out -->
  <min value="[integer]"/><!-- 1..1 Minimum Cardinality -->
  <max value="[string]"/><!-- 1..1 Maximum Cardinality (a number or *) -->
  <documentation value="[string]"/><!-- 0..1 Description of meaning/use -->
  <type value="[code]"/><!-- ?? 0..1 What type this parameter has -->
  <searchType value="[code]"/><!-- ?? 0..1 number | date | string | token | reference | composite | quantity | uri -->
  <profile><!-- 0..1 Reference(StructureDefinition) Profile on the type --></profile>
  <binding>  <!-- 0..1 ValueSet details if this is coded -->
   <strength value="[code]"/><!-- 1..1 required | extensible | preferred | example -->
   <valueSet[x]><!-- 1..1 uri|Reference(ValueSet) Source of value set --></valueSet[x]>
  </binding>
  <part><!-- ?? 0..* Content as for OperationDefinition.parameter Parts of a nested Parameter --></part>
 </parameter>
</OperationDefinition>

JSON Template

{doco
  "resourceType" : "OperationDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Logical URL to reference this operation definition
  "version" : "<string>", // Logical id for this version of the operation definition
  "name" : "<string>", // R!  Informal name for this operation
  "status" : "<code>", // R!  draft | active | retired
  "kind" : "<code>", // R!  operation | query
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date for this version of the operation definition
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<markdown>", // Natural language description of the operation
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<markdown>", // Why this resource has been created
  "idempotent" : <boolean>, // Whether content is unchanged by the operation
  "code" : "<code>", // R!  Name used to invoke the operation
  "comment" : "<string>", // Additional information about use
  "base" : { Reference(OperationDefinition) }, // Marks this as a profile of the base
  "system" : <boolean>, // R!  Invoke at the system level?
  "type" : ["<code>"], // Invoke at resource level for these type
  "instance" : <boolean>, // R!  Invoke on an instance?
  "parameter" : [{ // Parameters for the operation/query
    "name" : "<code>", // R!  Name in Parameters.parameter.name or in URL
    "use" : "<code>", // R!  in | out
    "min" : <integer>, // R!  Minimum Cardinality
    "max" : "<string>", // R!  Maximum Cardinality (a number or *)
    "documentation" : "<string>", // Description of meaning/use
    "type" : "<code>", // C? What type this parameter has
    "searchType" : "<code>", // C? number | date | string | token | reference | composite | quantity | uri
    "profile" : { Reference(StructureDefinition) }, // Profile on the type
    "binding" : { // ValueSet details if this is coded
      "strength" : "<code>", // R!  required | extensible | preferred | example
      // valueSet[x]: Source of value set. One of these 2:
      "valueSetUri" : "<uri>"
      "valueSetReference" : { Reference(ValueSet) }
    },
    "part" : [{ Content as for OperationDefinition.parameter }] // C? Parts of a nested Parameter
  }]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:OperationDefinition;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:OperationDefinition.url [ uri ]; # 0..1 Logical URL to reference this operation definition
  fhir:OperationDefinition.version [ string ]; # 0..1 Logical id for this version of the operation definition
  fhir:OperationDefinition.name [ string ]; # 1..1 Informal name for this operation
  fhir:OperationDefinition.status [ code ]; # 1..1 draft | active | retired
  fhir:OperationDefinition.kind [ code ]; # 1..1 operation | query
  fhir:OperationDefinition.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:OperationDefinition.date [ dateTime ]; # 0..1 Date for this version of the operation definition
  fhir:OperationDefinition.publisher [ string ]; # 0..1 Name of the publisher (Organization or individual)
  fhir:OperationDefinition.contact [ # 0..* Contact details of the publisher
    fhir:OperationDefinition.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:OperationDefinition.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:OperationDefinition.description [ markdown ]; # 0..1 Natural language description of the operation
  fhir:OperationDefinition.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:OperationDefinition.requirements [ markdown ]; # 0..1 Why this resource has been created
  fhir:OperationDefinition.idempotent [ boolean ]; # 0..1 Whether content is unchanged by the operation
  fhir:OperationDefinition.code [ code ]; # 1..1 Name used to invoke the operation
  fhir:OperationDefinition.comment [ string ]; # 0..1 Additional information about use
  fhir:OperationDefinition.base [ Reference(OperationDefinition) ]; # 0..1 Marks this as a profile of the base
  fhir:OperationDefinition.system [ boolean ]; # 1..1 Invoke at the system level?
  fhir:OperationDefinition.type [ code ], ... ; # 0..* Invoke at resource level for these type
  fhir:OperationDefinition.instance [ boolean ]; # 1..1 Invoke on an instance?
  fhir:OperationDefinition.parameter [ # 0..* Parameters for the operation/query
    fhir:OperationDefinition.parameter.name [ code ]; # 1..1 Name in Parameters.parameter.name or in URL
    fhir:OperationDefinition.parameter.use [ code ]; # 1..1 in | out
    fhir:OperationDefinition.parameter.min [ integer ]; # 1..1 Minimum Cardinality
    fhir:OperationDefinition.parameter.max [ string ]; # 1..1 Maximum Cardinality (a number or *)
    fhir:OperationDefinition.parameter.documentation [ string ]; # 0..1 Description of meaning/use
    fhir:OperationDefinition.parameter.type [ code ]; # 0..1 What type this parameter has
    fhir:OperationDefinition.parameter.searchType [ code ]; # 0..1 number | date | string | token | reference | composite | quantity | uri
    fhir:OperationDefinition.parameter.profile [ Reference(StructureDefinition) ]; # 0..1 Profile on the type
    fhir:OperationDefinition.parameter.binding [ # 0..1 ValueSet details if this is coded
      fhir:OperationDefinition.parameter.binding.strength [ code ]; # 1..1 required | extensible | preferred | example
      # OperationDefinition.parameter.binding.valueSet[x] : 1..1 Source of value set. One of these 2
        fhir:OperationDefinition.parameter.binding.valueSetUri [ uri ]
        fhir:OperationDefinition.parameter.binding.valueSetReference [ Reference(ValueSet) ]
    ];
    fhir:OperationDefinition.parameter.part [ See OperationDefinition.parameter ], ... ; # 0..* Parts of a nested Parameter
  ], ...;
]

Changes since DSTU2

OperationDefinition
OperationDefinition.description Type changed from string to markdown
OperationDefinition.useContext added
OperationDefinition.requirements Type changed from string to markdown
OperationDefinition.comment Renamed from notes to comment
OperationDefinition.parameter.type Change value set from http://hl7.org/fhir/ValueSet/operation-parameter-type to http://hl7.org/fhir/ValueSet/all-types
OperationDefinition.parameter.searchType added

See the Full Difference for further information

 

Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle)

5.6.3.1 Terminology Bindings

PathDefinitionTypeReference
OperationDefinition.status The lifecycle status of a Value Set or Concept Map.RequiredConformanceResourceStatus
OperationDefinition.kind Whether an operation is a normal operation or a query.RequiredOperationKind
OperationDefinition.useContext Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use.ExtensibleContext of Use ValueSet
OperationDefinition.type One of the resource types defined as part of FHIR.Requiredhttp://hl7.org/fhir/valueset/resource-typesResourceType
OperationDefinition.parameter.use Whether an operation parameter is an input or an output parameter.RequiredOperationParameterUse
OperationDefinition.parameter.type Either an abstract type, a resource or a data type.Requiredhttp://hl7.org/fhir/valueset/all-typesFHIRAllTypes
OperationDefinition.parameter.searchType Data types allowed to be used for search parameters.RequiredSearchParamType
OperationDefinition.parameter.binding.strength Indication of the degree of conformance expectations associated with a binding.RequiredBindingStrength

5.6.3.2 Constraints

  • opd-1: On OperationDefinition.parameter: Either a type must be provided, or parts (expression on OperationDefinition.parameter: type.exists() or part.exists())
  • opd-2: On OperationDefinition.parameter: A search type can only be specified for parameters of type string (expression on OperationDefinition.parameter: searchType implies type = 'string')

5.6.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
The CDS Hook operation is the core API request for CDS Hooks[base]/$cds-hook
Operations Defined by Resource Types
Apply[base]/ActivityDefinition/[id]/$apply
Data Requirements[base]/ActivityDefinition/[id]/$data-requirements
Concept Look Up[base]/CodeSystem/$lookup
Subsumption Testing[base]/CodeSystem/$subsumes | [base]/CodeSystem/[id]/$subsumes
Performing inferencing based on a set of codes - e.g. a mix of composition and decomposition[base]/CodeSystem/$infer | [base]/CodeSystem/[id]/$infer
Generate a Document[base]/Composition/$document | [base]/Composition/[id]/$document
Concept Translation[base]/ConceptMap/$translate | [base]/ConceptMap/[id]/$translate
Closure Table Maintenance[base]/$closure
Fetch a subset of the conformance resource[base]/Conformance/$subset | [base]/Conformance/[id]/$subset
Test if a server implements a client's required operations[base]/Conformance/$implements | [base]/Conformance/[id]/$implements
Test if a server implements a client's required operations[base]/Conformance/$conforms
Evaluate[base]/DecisionSupportServiceModule/[id]/$evaluate
Data Requirements[base]/DecisionSupportServiceModule/[id]/$data-requirements
Fetch Encounter Record[base]/Encounter/[id]/$everything
Data Requirements[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
Data Requirements[base]/Measure/[id]/$data-requirements
Process Message[base]/$process-message
Observation Statistics[base]/Observation/$stats | [base]/Observation/[id]/$stats
Find patient matches using MPI based logic[base]/Patient/$match
Fetch Patient Record[base]/Patient/$everything | [base]/Patient/[id]/$everything
Place[base]/PlanDefinition/[id]/$apply
Data Requirements[base]/PlanDefinition/[id]/$data-requirements
Populate Questionnaire[base]/Questionnaire/$populate | [base]/Questionnaire/[id]/$populate
Geneate HTML for Questionnaire[base]/Questionnaire/$populatehtml | [base]/Questionnaire/[id]/$populatehtml
Generate a link to a Questionnaire completion webpage[base]/Questionnaire/$populatelink | [base]/Questionnaire/[id]/$populatelink
Build Questionnaire[base]/StructureDefinition/$questionnaire | [base]/StructureDefinition/[id]/$questionnaire
Model Instance Transformation[base]/StructureMap/$transform | [base]/StructureMap/[id]/$transform
Reserve Task[base]/Task/[id]/$reserve
Start Task[base]/Task/[id]/$start
Finish Task[base]/Task/[id]/$finish
Fail Task[base]/Task/[id]/$fail
Release Task[base]/Task/[id]/$release
Suspend Task[base]/Task/[id]/$suspend
Resume Task[base]/Task/[id]/$resume
Cancel Task[base]/Task/[id]/$cancel
Stop Task[base]/Task/[id]/$stop
Set Task Input[base]/Task/[id]/$set-input
Set Task Output[base]/Task/[id]/$set-output
Value Set Expansion[base]/ValueSet/$expand | [base]/ValueSet/[id]/$expand
Value Set based Validation[base]/ValueSet/$validate-code | [base]/ValueSet/[id]/$validate-code
Operations Defined by Implementation Guides

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

5.6.3.5 Passing Resources to Operations

There are two ways to pass resources to an operation - directly, or by reference. Since the two forms have very 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.

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

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

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

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

NameTypeDescriptionPaths
basereferenceMarks this as a profile of the baseOperationDefinition.base
(OperationDefinition)
codetokenName used to invoke the operationOperationDefinition.code
contexttokenA use context assigned to the operation definitionOperationDefinition.useContext
datedateDate for this version of the operation definitionOperationDefinition.date
instancetokenInvoke on an instance?OperationDefinition.instance
kindtokenoperation | queryOperationDefinition.kind
namestringInformal name for this operationOperationDefinition.name
paramprofilereferenceProfile on the typeOperationDefinition.parameter.profile
(StructureDefinition)
publisherstringName of the publisher (Organization or individual)OperationDefinition.publisher
statustokendraft | active | retiredOperationDefinition.status
systemtokenInvoke at the system level?OperationDefinition.system
typetokenInvoke at resource level for these typeOperationDefinition.type
urluriLogical URL to reference this operation definitionOperationDefinition.url
versiontokenLogical id for this version of the operation definitionOperationDefinition.version