{
"description": "This structure is defined to allow the FHIR Validator to validate a CDSHooks Request Body. TODO: This content will be moved to the CDS Hooks specification in the future",
"_filename": "StructureDefinition-CDSHooksRequest.json",
"package_name": "hl7.fhir.uv.tools.r4",
"date": "2025-08-05T20:09:06+10:00",
"derivation": "specialization",
"publisher": "HL7 International / FHIR Infrastructure",
"fhirVersion": "4.0.1",
"jurisdiction": [ {
"coding": [ {
"code": "001",
"system": "http://unstats.un.org/unsd/methods/m49/m49.htm"
} ]
} ],
"name": "CDSHooksRequest",
"mapping": [ {
"uri": "http://hl7.org/v3",
"name": "RIM Mapping",
"identity": "rim"
} ],
"abstract": false,
"type": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest",
"experimental": "true",
"resourceType": "StructureDefinition",
"title": "CDSHooks Request (Logical Definition)",
"package_version": "0.8.0",
"extension": [ {
"url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm",
"valueInteger": 1
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-suppress-resourcetype",
"valueBoolean": true
}, {
"url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg",
"valueCode": "fhir"
} ],
"snapshot": {
"element": [ {
"constraint": [ {
"key": "cds-r-1",
"human": "if fhirAuthorization details are provided, a fhirServer SHALL be specified",
"severity": "error",
"expression": "fhirAuthorization.exists() implies fhirServer.exists()"
} ],
"path": "CDSHooksRequest",
"min": 0,
"definition": "The data structure that used when invoking a CDS Hook service",
"isModifier": false,
"short": "A request for decision support",
"max": "*",
"id": "CDSHooksRequest",
"base": {
"max": "*",
"min": 0,
"path": "Base"
}
}, {
"path": "CDSHooksRequest.extension",
"min": 0,
"definition": "A JSON object that has properties where the names are defined by the extension definitions",
"short": "Object that has Named Extension Properties",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksExtensions"
} ],
"max": "1",
"id": "CDSHooksRequest.extension",
"comment": "Extension structures SHOULD use a strategy for naming that ensures global uniqueness, such as reverse-domain-name notation, e.g. com.cds-hooks.sandbox.myextension-practitionerspecialty. How to handle complex extensions (objects) is not defined",
"base": {
"max": "1",
"min": 0,
"path": "CDSHooksElement.extension"
}
}, {
"id": "CDSHooksRequest.hook",
"max": "1",
"min": 1,
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.hook"
},
"path": "CDSHooksRequest.hook",
"type": [ {
"code": "code"
} ],
"short": "The hook that triggered this CDS Service call",
"definition": "The hook that triggered this CDS Service call"
}, {
"path": "CDSHooksRequest.hookInstance",
"min": 1,
"definition": "While working in the CDS Client, a user can perform multiple actions in series or in parallel. For example, a clinician might prescribe two drugs in a row; each prescription action would be assigned a unique hookInstance. This allows a CDS Service to uniquely identify each hook invocation",
"short": "A UUID for this particular hook call",
"type": [ {
"code": "uuid"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/implied-string-prefix",
"valueString": "urn:uuid:"
} ],
"max": "1",
"id": "CDSHooksRequest.hookInstance",
"comment": "Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable.",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.hookInstance"
}
}, {
"id": "CDSHooksRequest.fhirServer",
"max": "1",
"min": 0,
"base": {
"max": "1",
"min": 0,
"path": "CDSHooksRequest.fhirServer"
},
"path": "CDSHooksRequest.fhirServer",
"type": [ {
"code": "url"
} ],
"short": "The base URL of the CDS Client's FHIR server",
"definition": "The base URL of the CDS Client's FHIR server. If fhirAuthorization is provided, this field is REQUIRED. The scheme MUST be https when production data is exchanged"
}, {
"constraint": [ {
"key": "cds-r-2",
"human": "If the granted SMART scopes include patient scopes (i.e. 'patient/'), the patient field SHOULD be populated to identify the FHIR id of that patient.",
"severity": "error",
"expression": "scope.contains('Patient/') implies patient.exists()"
} ],
"path": "CDSHooksRequest.fhirAuthorization",
"min": 0,
"definition": "A structure holding an OAuth 2.0 bearer access token granting the CDS Service access to FHIR resources, along with supplemental information relating to the token",
"short": "Authorization info for service to use when querying",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement"
} ],
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization",
"base": {
"max": "1",
"min": 0,
"path": "CDSHooksRequest.fhirAuthorization"
}
}, {
"path": "CDSHooksRequest.fhirAuthorization.extension",
"min": 0,
"definition": "A JSON object that has properties where the names are defined by the extension definitions",
"short": "Object that has Named Extension Properties",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksExtensions"
} ],
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization.extension",
"comment": "Extension structures SHOULD use a strategy for naming that ensures global uniqueness, such as reverse-domain-name notation, e.g. com.cds-hooks.sandbox.myextension-practitionerspecialty. How to handle complex extensions (objects) is not defined",
"base": {
"max": "1",
"min": 0,
"path": "CDSHooksElement.extension"
}
}, {
"path": "CDSHooksRequest.fhirAuthorization.accessToken",
"min": 1,
"definition": "This is the OAuth 2.0 access token that provides access to the FHIR server",
"short": "OAuth 2.0 access token giving access to FHIR server",
"type": [ {
"code": "string"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-name",
"valueString": "access_token"
} ],
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization.accessToken",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.accessToken"
}
}, {
"path": "CDSHooksRequest.fhirAuthorization.tokenType",
"fixedCode": "Bearer",
"min": 1,
"definition": "The type of token provided. (Present to support future extensibility)",
"short": "Bearer",
"type": [ {
"code": "code"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-name",
"valueString": "token_type"
} ],
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization.tokenType",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.tokenType"
}
}, {
"path": "CDSHooksRequest.fhirAuthorization.expiresIn",
"min": 1,
"definition": "The lifetime in seconds of the access token.",
"short": "The lifetime in seconds of the access token",
"type": [ {
"code": "integer"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-name",
"valueString": "expires_in"
} ],
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization.expiresIn",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.expiresIn"
}
}, {
"id": "CDSHooksRequest.fhirAuthorization.scope",
"max": "1",
"min": 1,
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.scope"
},
"path": "CDSHooksRequest.fhirAuthorization.scope",
"type": [ {
"code": "string"
} ],
"short": "Scopes granted by access token",
"definition": "The scopes the access token grants the CDS Service"
}, {
"id": "CDSHooksRequest.fhirAuthorization.subject",
"max": "1",
"min": 1,
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.subject"
},
"path": "CDSHooksRequest.fhirAuthorization.subject",
"type": [ {
"code": "string"
} ],
"short": "OAuth 2.0 client identifier of the CDS Service",
"definition": "The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server"
}, {
"id": "CDSHooksRequest.fhirAuthorization.patient",
"max": "1",
"min": 0,
"base": {
"max": "1",
"min": 0,
"path": "CDSHooksRequest.fhirAuthorization.patient"
},
"path": "CDSHooksRequest.fhirAuthorization.patient",
"type": [ {
"code": "id"
} ],
"short": "OAuth 2.0 client identifier of the CDS Service",
"definition": "The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server"
}, {
"path": "CDSHooksRequest.context",
"min": 1,
"definition": "Hook-specific contextual data that the CDS service will need",
"short": "Contextual data always needed for this hook type",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookContext"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'appointment-book'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookAppointmentBookContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'encounter-start'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookEncounterStartContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'encounter-discharge'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookEncounterDischargeContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'patient-view'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookPatientViewContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-dispatch'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderDispatchContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-sign'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSignContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-select'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSelectContext"
} ]
} ],
"max": "1",
"id": "CDSHooksRequest.context",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.context"
}
}, {
"path": "CDSHooksRequest.prefetch",
"min": 0,
"definition": "An object containing key/value pairs of FHIR queries that this Request is requesting the CDS Client to perform and provide on each Request call. The key is a string that describes the type of data being requested and the value is a string representing the FHIR query",
"short": "Additional information requested by service for this hook type",
"type": [ {
"code": "Base"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-property-key",
"valueCode": "key"
} ],
"max": "*",
"id": "CDSHooksRequest.prefetch",
"base": {
"max": "*",
"min": 0,
"path": "CDSHooksRequest.prefetch"
}
}, {
"id": "CDSHooksRequest.prefetch.key",
"max": "1",
"min": 1,
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.prefetch.key"
},
"path": "CDSHooksRequest.prefetch.key",
"type": [ {
"code": "code"
} ],
"short": "Key of FHIR query",
"definition": "Name of the FHIR query/read from the CDS Hooks Services object provided by the server"
}, {
"path": "CDSHooksRequest.prefetch.value",
"min": 1,
"definition": "What was found by executing the search or read requested by the CDS Hooks Service in the context of this particular hook invocation",
"short": "Results of query/read",
"type": [ {
"code": "Resource"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-nullable",
"valueBoolean": true
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/id-expectation",
"valueCode": "optional"
} ],
"max": "1",
"id": "CDSHooksRequest.prefetch.value",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.prefetch.value"
}
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/snapshot-base-version",
"valueString": "0.8.0"
} ]
},
"status": "draft",
"id": "5fce14a7-0dc0-441b-8285-3359d3c823db",
"kind": "logical",
"url": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest",
"identifier": [ {
"value": "urn:oid:2.16.840.1.113883.4.642.40.1.42.6",
"system": "urn:ietf:rfc:3986"
} ],
"version": "0.8.0",
"differential": {
"element": [ {
"id": "CDSHooksRequest",
"path": "CDSHooksRequest",
"short": "A request for decision support",
"constraint": [ {
"key": "cds-r-1",
"human": "if fhirAuthorization details are provided, a fhirServer SHALL be specified",
"severity": "error",
"expression": "fhirAuthorization.exists() implies fhirServer.exists()"
} ],
"definition": "The data structure that used when invoking a CDS Hook service"
}, {
"id": "CDSHooksRequest.hook",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.hook",
"type": [ {
"code": "code"
} ],
"short": "The hook that triggered this CDS Service call",
"definition": "The hook that triggered this CDS Service call"
}, {
"path": "CDSHooksRequest.hookInstance",
"min": 1,
"definition": "While working in the CDS Client, a user can perform multiple actions in series or in parallel. For example, a clinician might prescribe two drugs in a row; each prescription action would be assigned a unique hookInstance. This allows a CDS Service to uniquely identify each hook invocation",
"short": "A UUID for this particular hook call",
"type": [ {
"code": "uuid"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/implied-string-prefix",
"valueString": "urn:uuid:"
} ],
"max": "1",
"id": "CDSHooksRequest.hookInstance",
"comment": "Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable."
}, {
"id": "CDSHooksRequest.fhirServer",
"max": "1",
"min": 0,
"path": "CDSHooksRequest.fhirServer",
"type": [ {
"code": "url"
} ],
"short": "The base URL of the CDS Client's FHIR server",
"definition": "The base URL of the CDS Client's FHIR server. If fhirAuthorization is provided, this field is REQUIRED. The scheme MUST be https when production data is exchanged"
}, {
"id": "CDSHooksRequest.fhirAuthorization",
"max": "1",
"min": 0,
"path": "CDSHooksRequest.fhirAuthorization",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement"
} ],
"short": "Authorization info for service to use when querying",
"constraint": [ {
"key": "cds-r-2",
"human": "If the granted SMART scopes include patient scopes (i.e. 'patient/'), the patient field SHOULD be populated to identify the FHIR id of that patient.",
"severity": "error",
"expression": "scope.contains('Patient/') implies patient.exists()"
} ],
"definition": "A structure holding an OAuth 2.0 bearer access token granting the CDS Service access to FHIR resources, along with supplemental information relating to the token"
}, {
"id": "CDSHooksRequest.fhirAuthorization.accessToken",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.accessToken",
"type": [ {
"code": "string"
} ],
"short": "OAuth 2.0 access token giving access to FHIR server",
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-name",
"valueString": "access_token"
} ],
"definition": "This is the OAuth 2.0 access token that provides access to the FHIR server"
}, {
"path": "CDSHooksRequest.fhirAuthorization.tokenType",
"fixedCode": "Bearer",
"min": 1,
"definition": "The type of token provided. (Present to support future extensibility)",
"short": "Bearer",
"type": [ {
"code": "code"
} ],
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-name",
"valueString": "token_type"
} ],
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization.tokenType"
}, {
"id": "CDSHooksRequest.fhirAuthorization.expiresIn",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.expiresIn",
"type": [ {
"code": "integer"
} ],
"short": "The lifetime in seconds of the access token",
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-name",
"valueString": "expires_in"
} ],
"definition": "The lifetime in seconds of the access token."
}, {
"id": "CDSHooksRequest.fhirAuthorization.scope",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.scope",
"type": [ {
"code": "string"
} ],
"short": "Scopes granted by access token",
"definition": "The scopes the access token grants the CDS Service"
}, {
"id": "CDSHooksRequest.fhirAuthorization.subject",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.subject",
"type": [ {
"code": "string"
} ],
"short": "OAuth 2.0 client identifier of the CDS Service",
"definition": "The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server"
}, {
"id": "CDSHooksRequest.fhirAuthorization.patient",
"max": "1",
"min": 0,
"path": "CDSHooksRequest.fhirAuthorization.patient",
"type": [ {
"code": "id"
} ],
"short": "OAuth 2.0 client identifier of the CDS Service",
"definition": "The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server"
}, {
"id": "CDSHooksRequest.context",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.context",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookContext"
} ],
"short": "Contextual data always needed for this hook type",
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'appointment-book'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookAppointmentBookContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'encounter-start'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookEncounterStartContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'encounter-discharge'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookEncounterDischargeContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'patient-view'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookPatientViewContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-dispatch'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderDispatchContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-sign'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSignContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-select'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSelectContext"
} ]
} ],
"definition": "Hook-specific contextual data that the CDS service will need"
}, {
"id": "CDSHooksRequest.prefetch",
"max": "*",
"min": 0,
"path": "CDSHooksRequest.prefetch",
"type": [ {
"code": "Base"
} ],
"short": "Additional information requested by service for this hook type",
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-property-key",
"valueCode": "key"
} ],
"definition": "An object containing key/value pairs of FHIR queries that this Request is requesting the CDS Client to perform and provide on each Request call. The key is a string that describes the type of data being requested and the value is a string representing the FHIR query"
}, {
"id": "CDSHooksRequest.prefetch.key",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.prefetch.key",
"type": [ {
"code": "code"
} ],
"short": "Key of FHIR query",
"definition": "Name of the FHIR query/read from the CDS Hooks Services object provided by the server"
}, {
"id": "CDSHooksRequest.prefetch.value",
"max": "1",
"min": 1,
"path": "CDSHooksRequest.prefetch.value",
"type": [ {
"code": "Resource"
} ],
"short": "Results of query/read",
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-nullable",
"valueBoolean": true
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/id-expectation",
"valueCode": "optional"
} ],
"definition": "What was found by executing the search or read requested by the CDS Hooks Service in the context of this particular hook invocation"
} ]
},
"contact": [ {
"telecom": [ {
"value": "http://www.hl7.org/Special/committees/fiwg",
"system": "url"
} ]
} ],
"baseDefinition": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement"
}