PATIENT ADMINISTRTAION (PA) Workgroup Development Draft

6.18 Resource OperationDefinition - Content

This resource maintained by the FHIR Management Group Work Group

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

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

6.18.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]

6.18.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 profile
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*ElementContact details of the publisher
.... name Σ0..1stringName of a individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description 0..1stringNatural language description of the operation
... requirements 0..1stringWhy is this needed?
... status ?!1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental 0..1booleanIf for testing purposes, not real usage
... date 0..1dateTimeDate for this version of the operation definition
... kind 1..1codeoperation | query
OperationKind (Required)
... idempotent 0..1booleanWhether operation causes changes to content
... code 1..1codeName used to invoke the operation
... notes 0..1stringAdditional information about use
... base 0..1OperationDefinitionMarks 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..*ElementParameters for the operation/query
Either a type must be provided, or parts
.... name 1..1codeName of the parameter
.... 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 hs
Parameter Types used in Operation Definitions (Required)
.... profile 0..1StructureDefinitionProfile on the type
.... part I0..*ElementParts of a Tuple Parameter
..... name 1..1codeName of the parameter
..... min 1..1unsignedIntMinimum Cardinality
..... max 1..1stringMaximum Cardinality (a number or *)
..... documentation 0..1stringDescription of meaning/use
..... type 1..1codeWhat type this parameter hs
Parameter Types used in Operation Definitions (Required)
..... profile 0..1StructureDefinitionProfile on the type

UML Diagram

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 (should be globally unique uri)url : uri 0..1The 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..1A free text natural language name identifying the Profilename : string 1..1The name of the individual or organization that published the operation definitionpublisher : string 0..1A free text natural language description of the profile and its usedescription : string 0..1Explains why this operation definition is needed and why it's been constrained as it hasrequirements : string 0..1The 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 MapConformanceResourceStatus »This profile was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean 0..1The date that this version of the profile was publisheddate : dateTime 0..1Whether this is operation or named querykind : code 1..1 « Whether an operation is a normal operation or a queryOperationKind »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..1The name used to invoke the operationcode : code 1..1Additional information about how to use this operation or named querynotes : string 0..1Indicates that this operation definition is a constraining profile on the basebase : Reference(OperationDefinition) 0..1Indicates 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..1Indicates 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 FHIRResourceType »Indicates whether this operation can be invoked on a particular instance of one of the given typesinstance : boolean 1..1ContactThe name of an individual to contact regarding the operation definitionname : string 0..1Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint 0..*ParameterThe name of used to identify the parametername : code 1..1Whether this is an input or an output parameteruse : code 1..1 « Whether an operation parameter is an input or an output parameterOperationParameterUse »The minimum number of times this parameter SHALL appear in the request or responsemin : integer 1..1The maximum number of times this element is permitted to appear in the request or responsemax : string 1..1Describes the meaning or use of this parameterdocumentation : string 0..1The type for this parametertype : code 0..1 « The type of a parameterParameter Types used in Operation Definitions »A profile the specifies the rules that this parameter must conform toprofile : Reference(StructureDefinition) 0..1PartThe name of used to identify the parametername : code 1..1The minimum number of times this parameter SHALL appear in the request or responsemin : unsignedInt 1..1The maximum number of times this element is permitted to appear in the request or responsemax : string 1..1Describes the meaning or use of this parameterdocumentation : string 0..1The type for this parametertype : code 1..1 « The type of a parameterParameter Types used in Operation Definitions »A profile the specifies the rules that this parameter must conform toprofile : Reference(StructureDefinition) 0..1Contacts to assist a user in finding and communicating with the publishercontact0..*The parts of a Tuple Parameterpart0..*The parameters for the operation/queryparameter0..*

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 profile -->
 <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 a individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[string]"/><!-- 0..1 Natural language description of the operation -->
 <requirements value="[string]"/><!-- 0..1 Why is this needed? -->
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <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 -->
 <kind value="[code]"/><!-- 1..1 operation | query -->
 <idempotent value="[boolean]"/><!-- 0..1 Whether operation causes changes to content -->
 <code value="[code]"/><!-- 1..1 Name used to invoke the operation -->
 <notes 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 of the parameter -->
  <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 hs -->
  <profile><!-- 0..1 Reference(StructureDefinition) Profile on the type --></profile>
  <part>  <!-- ?? 0..* Parts of a Tuple Parameter -->
   <name value="[code]"/><!-- 1..1 Name of the parameter -->
   <min value="[unsignedInt]"/><!-- 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]"/><!-- 1..1 What type this parameter hs -->
   <profile><!-- 0..1 Reference(StructureDefinition) Profile on the type --></profile>
  </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 profile
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of a individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<string>", // Natural language description of the operation
  "requirements" : "<string>", // Why is this needed?
  "status" : "<code>", // R!  draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date for this version of the operation definition
  "kind" : "<code>", // R!  operation | query
  "idempotent" : <boolean>, // Whether operation causes changes to content
  "code" : "<code>", // R!  Name used to invoke the operation
  "notes" : "<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 of the parameter
    "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 hs
    "profile" : { Reference(StructureDefinition) }, // Profile on the type
    "part" : [{ // C? Parts of a Tuple Parameter
      "name" : "<code>", // R!  Name of the parameter
      "min" : "<unsignedInt>", // R!  Minimum Cardinality
      "max" : "<string>", // R!  Maximum Cardinality (a number or *)
      "documentation" : "<string>", // Description of meaning/use
      "type" : "<code>", // R!  What type this parameter hs
      "profile" : { Reference(StructureDefinition) } // Profile on the type
    }]
  }]
}

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 profile
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*ElementContact details of the publisher
.... name Σ0..1stringName of a individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description 0..1stringNatural language description of the operation
... requirements 0..1stringWhy is this needed?
... status ?!1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental 0..1booleanIf for testing purposes, not real usage
... date 0..1dateTimeDate for this version of the operation definition
... kind 1..1codeoperation | query
OperationKind (Required)
... idempotent 0..1booleanWhether operation causes changes to content
... code 1..1codeName used to invoke the operation
... notes 0..1stringAdditional information about use
... base 0..1OperationDefinitionMarks 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..*ElementParameters for the operation/query
Either a type must be provided, or parts
.... name 1..1codeName of the parameter
.... 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 hs
Parameter Types used in Operation Definitions (Required)
.... profile 0..1StructureDefinitionProfile on the type
.... part I0..*ElementParts of a Tuple Parameter
..... name 1..1codeName of the parameter
..... min 1..1unsignedIntMinimum Cardinality
..... max 1..1stringMaximum Cardinality (a number or *)
..... documentation 0..1stringDescription of meaning/use
..... type 1..1codeWhat type this parameter hs
Parameter Types used in Operation Definitions (Required)
..... profile 0..1StructureDefinitionProfile on the type

UML Diagram

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 (should be globally unique uri)url : uri 0..1The 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..1A free text natural language name identifying the Profilename : string 1..1The name of the individual or organization that published the operation definitionpublisher : string 0..1A free text natural language description of the profile and its usedescription : string 0..1Explains why this operation definition is needed and why it's been constrained as it hasrequirements : string 0..1The 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 MapConformanceResourceStatus »This profile was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean 0..1The date that this version of the profile was publisheddate : dateTime 0..1Whether this is operation or named querykind : code 1..1 « Whether an operation is a normal operation or a queryOperationKind »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..1The name used to invoke the operationcode : code 1..1Additional information about how to use this operation or named querynotes : string 0..1Indicates that this operation definition is a constraining profile on the basebase : Reference(OperationDefinition) 0..1Indicates 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..1Indicates 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 FHIRResourceType »Indicates whether this operation can be invoked on a particular instance of one of the given typesinstance : boolean 1..1ContactThe name of an individual to contact regarding the operation definitionname : string 0..1Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint 0..*ParameterThe name of used to identify the parametername : code 1..1Whether this is an input or an output parameteruse : code 1..1 « Whether an operation parameter is an input or an output parameterOperationParameterUse »The minimum number of times this parameter SHALL appear in the request or responsemin : integer 1..1The maximum number of times this element is permitted to appear in the request or responsemax : string 1..1Describes the meaning or use of this parameterdocumentation : string 0..1The type for this parametertype : code 0..1 « The type of a parameterParameter Types used in Operation Definitions »A profile the specifies the rules that this parameter must conform toprofile : Reference(StructureDefinition) 0..1PartThe name of used to identify the parametername : code 1..1The minimum number of times this parameter SHALL appear in the request or responsemin : unsignedInt 1..1The maximum number of times this element is permitted to appear in the request or responsemax : string 1..1Describes the meaning or use of this parameterdocumentation : string 0..1The type for this parametertype : code 1..1 « The type of a parameterParameter Types used in Operation Definitions »A profile the specifies the rules that this parameter must conform toprofile : Reference(StructureDefinition) 0..1Contacts to assist a user in finding and communicating with the publishercontact0..*The parts of a Tuple Parameterpart0..*The parameters for the operation/queryparameter0..*

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 profile -->
 <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 a individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[string]"/><!-- 0..1 Natural language description of the operation -->
 <requirements value="[string]"/><!-- 0..1 Why is this needed? -->
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <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 -->
 <kind value="[code]"/><!-- 1..1 operation | query -->
 <idempotent value="[boolean]"/><!-- 0..1 Whether operation causes changes to content -->
 <code value="[code]"/><!-- 1..1 Name used to invoke the operation -->
 <notes 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 of the parameter -->
  <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 hs -->
  <profile><!-- 0..1 Reference(StructureDefinition) Profile on the type --></profile>
  <part>  <!-- ?? 0..* Parts of a Tuple Parameter -->
   <name value="[code]"/><!-- 1..1 Name of the parameter -->
   <min value="[unsignedInt]"/><!-- 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]"/><!-- 1..1 What type this parameter hs -->
   <profile><!-- 0..1 Reference(StructureDefinition) Profile on the type --></profile>
  </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 profile
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of a individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<string>", // Natural language description of the operation
  "requirements" : "<string>", // Why is this needed?
  "status" : "<code>", // R!  draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date for this version of the operation definition
  "kind" : "<code>", // R!  operation | query
  "idempotent" : <boolean>, // Whether operation causes changes to content
  "code" : "<code>", // R!  Name used to invoke the operation
  "notes" : "<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 of the parameter
    "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 hs
    "profile" : { Reference(StructureDefinition) }, // Profile on the type
    "part" : [{ // C? Parts of a Tuple Parameter
      "name" : "<code>", // R!  Name of the parameter
      "min" : "<unsignedInt>", // R!  Minimum Cardinality
      "max" : "<string>", // R!  Maximum Cardinality (a number or *)
      "documentation" : "<string>", // Description of meaning/use
      "type" : "<code>", // R!  What type this parameter hs
      "profile" : { Reference(StructureDefinition) } // Profile on the type
    }]
  }]
}

 

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

6.18.3.1 Terminology Bindings

PathDefinitionTypeReference
OperationDefinition.status The lifecycle status of a Value Set or Concept MapRequiredhttp://hl7.org/fhir/conformance-resource-status
OperationDefinition.kind Whether an operation is a normal operation or a queryRequiredhttp://hl7.org/fhir/operation-kind
OperationDefinition.type One of the resource types defined as part of FHIRRequiredhttp://hl7.org/fhir/valueset/resource-types
OperationDefinition.parameter.use Whether an operation parameter is an input or an output parameterRequiredhttp://hl7.org/fhir/operation-parameter-use
OperationDefinition.parameter.type
OperationDefinition.parameter.part.type
The type of a parameterRequiredhttp://hl7.org/fhir/vs/operation-parameter-type

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

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
Generate a Document[base]/Composition/$document
Concept Translation[base]/ConceptMap/$translate | [base]/ConceptMap/[id]/$translate
Batch Mode Translation[base]/ConceptMap/$batch
Closure Table Maintenance[base]/$closure
Fetch Encounter Record[base]/Encounter/[id]/$everything
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
Batch Mode Validation[base]/ValueSet/$batch

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 are also limited to a single return parameter "result" (though this may repeat).

6.18.3.5 Renaming OperationDefinition.name

It's possible for two different organisations 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 a little 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 on 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 organisations (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.6 Determining System Compatibility

A client can determine the compatiblity 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 paramters it uses are supported by the server. 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.7 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 a 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.

NameTypeDescriptionPaths
basereferenceMarks this as a profile of the baseOperationDefinition.base
(OperationDefinition)
codetokenName used to invoke the operationOperationDefinition.code
datedateDate for this version of the operation definitionOperationDefinition.date
instancetokenInvoke on an instance?OperationDefinition.instance
kindtokenoperation | queryOperationDefinition.kind
namestringInformal name for this profileOperationDefinition.name
profilereferenceProfile 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