GuidanceResponse — Sortie d'un moteur de décision

Le pendant de l'opération $apply (PlanDefinition / ActivityDefinition) et de CDS Hooks : une trace formalisée de la guidance retournée à l'utilisateur clinique.

Objet de la ressource

GuidanceResponse capture la réponse d'un module de guidance — moteur CQL, hook CDS Hooks, service externe — quand on lui soumet un contexte clinique. Elle relie la requête initiale, le module évalué, les données d'entrée et les recommandations produites.

En pratique, GuidanceResponse est rarement créée à la main : c'est un sous-produit de $apply sur un PlanDefinition ou de la réponse JSON d'un service CDS Hooks.

Champs clés

Champ	Type	Cardinalité	Rôle
`requestIdentifier`	Identifier	0..1	Identifiant logique de la requête initiale.
`identifier`	Identifier[]	0..*	Identifiants métier.
`module[x]`	uri \| canonical \| CodeableConcept	1..1	Module de guidance évalué (PlanDefinition canonique).
`status`	code	1..1	`success \| data-requested \| data-required \| in-progress \| failure \| entered-in-error`.
`subject`	Reference(Patient \| Group)	0..1	Sujet évalué.
`encounter`	Reference(Encounter)	0..1	Contexte de l'évaluation.
`occurrenceDateTime`	dateTime	0..1	Quand la guidance a été produite.
`performer`	Reference(Device)	0..1	Moteur ayant produit la réponse.
`reason`	CodeableReference[]	0..*	Pourquoi la guidance a été demandée.
`evaluationMessage`	Reference(OperationOutcome)[]	0..*	Messages d'évaluation (erreurs, warnings).
`outputParameters`	Reference(Parameters)	0..1	Paramètres en sortie.
`result`	Reference(Appointment \| CarePlan \| RequestOrchestration…)[]	0..*	Ressources produites (recommandations).
`dataRequirement`	DataRequirement[]	0..*	Données manquantes nécessaires pour évaluer.

Exemple JSON

json guidanceresponse-example.json

{
  "resourceType": "GuidanceResponse",
  "id": "example",
  "requestIdentifier": {
    "system": "urn:ietf:rfc:3986",
    "value": "guidancereq-001"
  },
  "moduleCanonical": "http://example.org/PlanDefinition/cdc-opioid-guidance",
  "status": "success",
  "subject": { "reference": "Patient/example" },
  "occurrenceDateTime": "2026-05-15T10:32:00Z",
  "performer": { "reference": "Device/cds-engine" },
  "reason": [{
    "concept": {
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "182888003",
        "display": "Medication requested"
      }]
    }
  }],
  "result": [{
    "reference": "CarePlan/cdc-opioid-care-plan"
  }]
}

Lien avec CDS Hooks

CDS Hooks est le protocole HTTP léger publié par HL7 qui permet à un EHR d'appeler un service externe quand l'utilisateur ouvre une fenêtre clinique (patient-view, medication-prescribe…). Le service répond avec des cards JSON. GuidanceResponse est la projection FHIR de cette réponse : chaque card peut être stockée pour audit ou pour ré-utilisation.

Pièges courants

status=data-required ignoré — l'appelant doit interpréter dataRequirement et relancer l'évaluation avec les données manquantes.
Confusion avec OperationOutcome — GuidanceResponse porte la guidance, OperationOutcome les messages techniques. Les deux peuvent coexister.
Module non versionné — la traçabilité s'effondre si module ne pointe pas une version stable.

Ressources liées

PlanDefinition — module évalué.
ActivityDefinition — action atomique invoquée.
RequestOrchestration — sortie possible.
OperationOutcome — messages d'évaluation.
Hub FHIR R5.

Fondamentaux

Standards

Messages phares

Outils