OperationDefinition — detail: FHIR operations
Machine-readable specification of FHIR operations ($everything,
$validate, $translate, $evaluate-measure...).
Allows clients to discover advanced server capabilities.
Role of $-prefixed operations
FHIR operations step outside pure REST (GET/POST/PUT/DELETE) to expose transactional
business functions: POST /Patient/123/$everything,
POST /ConceptMap/$translate. OperationDefinition publishes the contract of
these operations.
system, type, instance
| Level | URL | Example |
|---|---|---|
system=true | POST /$op | $convert (at server root) |
type=true | POST /[type]/$op | POST /Patient/$match |
instance=true | POST /[type]/[id]/$op | POST /Patient/123/$everything |
parameters in/out
Each operation declares its typed parameters:
use=in— input.use=out— output.min,max— cardinality.type— FHIR type (string, date, Bundle, resource).searchType— for search parameters.part— sub-parameters (composite parameters).
Example: Patient $everything
{
"resourceType": "OperationDefinition",
"id": "patient-everything",
"url": "http://hl7.org/fhir/OperationDefinition/Patient-everything",
"version": "5.0.0",
"name": "Everything",
"title": "Fetch Patient Record",
"status": "active",
"kind": "operation",
"code": "everything",
"resource": ["Patient"],
"system": false,
"type": false,
"instance": true,
"parameter": [{
"name": "start",
"use": "in",
"min": 0,
"max": "1",
"type": "date",
"documentation": "The date range relates to care dates, not record currency dates."
}, {
"name": "end",
"use": "in",
"min": 0,
"max": "1",
"type": "date"
}, {
"name": "return",
"use": "out",
"min": 1,
"max": "1",
"type": "Bundle",
"documentation": "The bundle type is searchset."
}]
}Common pitfalls
- kind=query instead of operation —
queryis for parameterised searches (search alias),operationfor effective actions. - No return parameter — every operation must declare its
out. - system/type/instance all false — at least one must be
true. - Mutable canonical URL — the URL must not change between versions.