OperationDefinition — Décrire les $operations FHIR

FHIR ne se limite pas au CRUD REST. Les opérations métier complexes — récupérer un dossier complet, expansion d'un ValueSet, validation d'une ressource — passent par des $operations normalisées via OperationDefinition.

Objet de la ressource

OperationDefinition est la métadonnée technique qui décrit une opération exécutable sur un serveur FHIR. C'est l'équivalent d'une définition de procédure stockée SQL : nom (le $code), paramètres d'entrée et de sortie, scope d'invocation (system, type ou instance).

Toutes les opérations standard FHIR ($validate, $everything, $expand, $lookup, $translate, $process-message…) ont une OperationDefinition publiée dans le core spec. Les implémentations peuvent définir leurs propres opérations privées via une OperationDefinition à URL canonique privée.

Champs clés

Kind et scope d'invocation

Trois booléens définissent où une opération peut être invoquée :

• system: true — invocable sur l'endpoint serveur, ex : POST [base]/$process-message.
• type: true — invocable sur un type de ressource, ex : POST [base]/Patient/$match.
• instance: true — invocable sur une instance, ex : GET [base]/Patient/123/$everything.

Une opération peut être invocable à plusieurs niveaux. $validate par exemple est type=true ET instance=true.

Exemple JSON

L'OperationDefinition canonique de 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",
  "experimental": false,
  "date": "2026-05-14",
  "publisher": "HL7 (FHIR Project)",
  "description": "Retourne toutes les ressources liées à un patient donné. Composé du Patient lui-même, de ses Encounter, Observation, Condition, MedicationStatement, etc.",
  "affectsState": false,
  "code": "everything",
  "resource": ["Patient"],
  "system": false,
  "type": false,
  "instance": true,
  "parameter": [
    {
      "name": "start",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "Date la plus ancienne des ressources retournées.",
      "type": "date"
    },
    {
      "name": "end",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "Date la plus récente des ressources retournées.",
      "type": "date"
    },
    {
      "name": "_since",
      "use": "in",
      "min": 0,
      "max": "1",
      "documentation": "Filtre par lastUpdated.",
      "type": "instant"
    },
    {
      "name": "_type",
      "use": "in",
      "min": 0,
      "max": "*",
      "documentation": "Restreint aux types de ressources listés.",
      "type": "code"
    },
    {
      "name": "return",
      "use": "out",
      "min": 1,
      "max": "1",
      "documentation": "Bundle searchset des ressources liées.",
      "type": "Bundle"
    }
  ]
}

Pièges courants

• Oublier affectsState — les serveurs autorisent GET seulement si affectsState=false. Une opération de lecture pure DOIT le déclarer.
• Scope mal déclaré — invoquer $everything sur /Patient sans id échoue car l'opération est instance=true uniquement.
• Paramètres typés Resource sans type concret — un paramètre type: Resource autorise tout, à éviter sauf cas explicite (ex : $validate).
• Pas d'OperationDefinition pour une opération privée — sans la déclarer dans la CapabilityStatement et publier l'OperationDefinition, aucun client générique ne saura l'appeler.

Ressources liées

• CapabilityStatement — référence les OperationDefinition supportées par le serveur.
• Parameters — ressource conteneur des entrées/sorties d'une $operation.
• OperationOutcome — format de retour d'erreur.
• ImplementationGuide — packager d'OperationDefinition métier.