GuidanceResponse — Output of a decision engine
The counterpart of the $apply operation (PlanDefinition / ActivityDefinition) and of CDS Hooks: a formalised trace of the guidance returned to the clinical user.
Purpose of the resource
GuidanceResponse captures the response of a guidance module — CQL engine, CDS Hooks hook, external service — when given a clinical context. It links the initial request, the evaluated module, the input data and the produced recommendations.
In practice, GuidanceResponse is rarely created by hand: it is a by-product of $apply
on a PlanDefinition or of the JSON response of a CDS Hooks service.
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
requestIdentifier | Identifier | 0..1 | Logical id of the initial request. |
identifier | Identifier[] | 0..* | Business identifiers. |
module[x] | uri | canonical | CodeableConcept | 1..1 | Evaluated guidance module (canonical PlanDefinition). |
status | code | 1..1 | success | data-requested | data-required | in-progress | failure | entered-in-error. |
subject | Reference(Patient | Group) | 0..1 | Evaluated subject. |
encounter | Reference(Encounter) | 0..1 | Evaluation context. |
occurrenceDateTime | dateTime | 0..1 | When the guidance was produced. |
performer | Reference(Device) | 0..1 | Engine that produced the response. |
reason | CodeableReference[] | 0..* | Why the guidance was requested. |
evaluationMessage | Reference(OperationOutcome)[] | 0..* | Evaluation messages (errors, warnings). |
outputParameters | Reference(Parameters) | 0..1 | Output parameters. |
result | Reference(Appointment | CarePlan | RequestOrchestration…)[] | 0..* | Produced resources (recommendations). |
dataRequirement | DataRequirement[] | 0..* | Missing data needed for evaluation. |
JSON example
{
"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"
}]
}CDS Hooks linkage
CDS Hooks is the lightweight HTTP protocol published by HL7 that lets an EHR call an external
service when the user opens a clinical context (patient-view,
medication-prescribe…). The service responds with JSON cards.
GuidanceResponse is the FHIR projection of that response: each card can be stored for audit or
reuse.
Common pitfalls
- Ignoring
status=data-required— the caller must interpretdataRequirementand replay the evaluation with the missing data. - Confusion with OperationOutcome — GuidanceResponse carries guidance, OperationOutcome carries technical messages. Both may coexist.
- Unversioned module — traceability collapses if
moduledoes not pin a stable version.
Related resources
- PlanDefinition — evaluated module.
- ActivityDefinition — atomic action invoked.
- RequestOrchestration — possible output.
- OperationOutcome — evaluation messages.
- FHIR R5 hub.