{
"description": "Defines CRD-specific constraints on the CDS Hooks Request logical model",
"_filename": "StructureDefinition-CRDHooksRequest.json",
"package_name": "hl7.fhir.us.davinci-crd",
"date": "2025-08-06T17:27:13+00:00",
"derivation": "constraint",
"publisher": "HL7 International / Financial Management",
"fhirVersion": "4.0.1",
"jurisdiction": [ {
"coding": [ {
"code": "US",
"system": "urn:iso:std:iso:3166"
} ]
} ],
"name": "CRDHooksRequest",
"abstract": false,
"type": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest",
"experimental": null,
"resourceType": "StructureDefinition",
"title": "CRD CDSHooks Request (Logical Definition)",
"package_version": "2.2.0-ballot",
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-suppress-resourcetype",
"valueBoolean": true
}, {
"url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg",
"valueCode": "fm"
}, {
"url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm",
"valueInteger": 4,
"_valueInteger": {
"extension": [ {
"url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom",
"valueCanonical": "http://hl7.org/fhir/us/davinci-crd/ImplementationGuide/davinci-crd"
} ]
}
}, {
"url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status",
"valueCode": "trial-use",
"_valueCode": {
"extension": [ {
"url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom",
"valueCanonical": "http://hl7.org/fhir/us/davinci-crd/ImplementationGuide/davinci-crd"
} ]
}
} ],
"snapshot": {
"element": [ {
"constraint": [ {
"key": "cds-r-1",
"human": "if fhirAuthorization details are provided, a fhirServer SHALL be specified",
"source": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest",
"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": "Request for decision support",
"max": "*",
"id": "CDSHooksRequest",
"base": {
"max": "*",
"min": 0,
"path": "Base"
}
}, {
"id": "CDSHooksRequest.extension",
"max": "1",
"min": 0,
"base": {
"max": "1",
"min": 0,
"path": "CDSHooksElement.extension"
},
"path": "CDSHooksRequest.extension",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksExtensions"
} ],
"short": "Extension",
"definition": "An Extension"
}, {
"path": "CDSHooksRequest.hook",
"min": 1,
"definition": "The hook that triggered this CDS Service call",
"short": "Hook event triggering call",
"type": [ {
"code": "code"
} ],
"mustSupport": true,
"binding": {
"strength": "required",
"valueSet": "http://hl7.org/fhir/us/davinci-crd/ValueSet/cdsHookType"
},
"max": "1",
"id": "CDSHooksRequest.hook",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.hook"
}
}, {
"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": "Unique id for hook invocation",
"type": [ {
"code": "uuid"
} ],
"mustSupport": true,
"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"
}
}, {
"path": "CDSHooksRequest.fhirServer",
"min": 1,
"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",
"short": "Location to query for data",
"type": [ {
"code": "url"
} ],
"mustSupport": true,
"max": "1",
"id": "CDSHooksRequest.fhirServer",
"base": {
"max": "1",
"min": 0,
"path": "CDSHooksRequest.fhirServer"
}
}, {
"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.",
"source": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest",
"severity": "error",
"expression": "scope.contains('Patient/') implies patient.exists()"
} ],
"path": "CDSHooksRequest.fhirAuthorization",
"min": 1,
"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": "Auth to use in queries",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement"
} ],
"mustSupport": true,
"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": "Auth token for query header",
"type": [ {
"code": "string"
} ],
"mustSupport": true,
"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"
} ],
"mustSupport": true,
"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": "Seconds token is valid",
"type": [ {
"code": "integer"
} ],
"mustSupport": true,
"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"
}
}, {
"path": "CDSHooksRequest.fhirAuthorization.scope",
"min": 1,
"definition": "The scopes the access token grants the CDS Service",
"short": "Granted access scopes",
"type": [ {
"code": "string"
} ],
"mustSupport": true,
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization.scope",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.scope"
}
}, {
"path": "CDSHooksRequest.fhirAuthorization.subject",
"min": 1,
"definition": "If the granted SMART scopes include patient scopes (i.e. 'patient/'), the access token is restricted to a specific patient. This field SHOULD be populated to identify the FHIR id of that patient.",
"short": "Patient id for access",
"type": [ {
"code": "string"
} ],
"mustSupport": true,
"max": "1",
"id": "CDSHooksRequest.fhirAuthorization.subject",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization.subject"
}
}, {
"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": "Context for decision support",
"type": [ {
"code": "http://hl7.org/fhir/tools/StructureDefinition/CDSHookContext"
} ],
"mustSupport": true,
"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": "Prefetch info requested by server",
"type": [ {
"code": "Base"
} ],
"mustSupport": true,
"extension": [ {
"url": "http://hl7.org/fhir/tools/StructureDefinition/json-property-key",
"valueCode": "key"
} ],
"max": "*",
"id": "CDSHooksRequest.prefetch",
"comment": "While this is mustSupport, CRD clients are not required to pass any or all prefetch data requested by the CRD service.",
"base": {
"max": "*",
"min": 0,
"path": "CDSHooksRequest.prefetch"
}
}, {
"path": "CDSHooksRequest.prefetch.key",
"min": 1,
"definition": "Name of the FHIR query/read from the CDS Hooks Services object provided by the server",
"short": "Key as specfied in server prefetch config",
"type": [ {
"code": "code"
} ],
"mustSupport": true,
"max": "1",
"id": "CDSHooksRequest.prefetch.key",
"base": {
"max": "1",
"min": 1,
"path": "CDSHooksRequest.prefetch.key"
}
}, {
"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": "Resource(s) matching prefetch criteria",
"type": [ {
"code": "Resource"
} ],
"mustSupport": true,
"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": "active",
"id": "f95e0e60-eb8c-4f21-b4a3-57fa25cc1cab",
"kind": "logical",
"url": "http://hl7.org/fhir/us/davinci-crd/StructureDefinition/CRDHooksRequest",
"identifier": [ {
"value": "urn:oid:2.16.840.1.113883.4.642.40.18.42.34",
"system": "urn:ietf:rfc:3986"
} ],
"version": "2.2.0-ballot",
"differential": {
"element": [ {
"id": "CDSHooksRequest",
"path": "CDSHooksRequest",
"short": "Request for decision support"
}, {
"id": "CDSHooksRequest.extension",
"path": "CDSHooksRequest.extension"
}, {
"id": "CDSHooksRequest.hook",
"path": "CDSHooksRequest.hook",
"type": [ {
"code": "code"
} ],
"short": "Hook event triggering call",
"binding": {
"strength": "required",
"valueSet": "http://hl7.org/fhir/us/davinci-crd/ValueSet/cdsHookType"
},
"mustSupport": true
}, {
"id": "CDSHooksRequest.hookInstance",
"path": "CDSHooksRequest.hookInstance",
"short": "Unique id for hook invocation",
"mustSupport": true
}, {
"id": "CDSHooksRequest.fhirServer",
"min": 1,
"path": "CDSHooksRequest.fhirServer",
"short": "Location to query for data",
"mustSupport": true
}, {
"id": "CDSHooksRequest.fhirAuthorization",
"min": 1,
"path": "CDSHooksRequest.fhirAuthorization",
"short": "Auth to use in queries",
"mustSupport": true
}, {
"id": "CDSHooksRequest.fhirAuthorization.accessToken",
"path": "CDSHooksRequest.fhirAuthorization.accessToken",
"short": "Auth token for query header",
"mustSupport": true
}, {
"id": "CDSHooksRequest.fhirAuthorization.tokenType",
"path": "CDSHooksRequest.fhirAuthorization.tokenType",
"mustSupport": true
}, {
"id": "CDSHooksRequest.fhirAuthorization.expiresIn",
"path": "CDSHooksRequest.fhirAuthorization.expiresIn",
"short": "Seconds token is valid",
"mustSupport": true
}, {
"id": "CDSHooksRequest.fhirAuthorization.scope",
"path": "CDSHooksRequest.fhirAuthorization.scope",
"short": "Granted access scopes",
"mustSupport": true
}, {
"id": "CDSHooksRequest.fhirAuthorization.subject",
"path": "CDSHooksRequest.fhirAuthorization.subject",
"short": "Patient id for access",
"definition": "If the granted SMART scopes include patient scopes (i.e. 'patient/'), the access token is restricted to a specific patient. This field SHOULD be populated to identify the FHIR id of that patient.",
"mustSupport": true
}, {
"id": "CDSHooksRequest.context",
"path": "CDSHooksRequest.context",
"short": "Context for decision support",
"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/us/davnci-crd/StructureDefinition/CRDHookAppointmentBookContext"
} ]
}, {
"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/CDSEncounterStartContext"
} ]
}, {
"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/CDSEncounterDischargeContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-dispatch'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/us/davnci-crd/StructureDefinition/CRDOrderDispatchContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-select'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/us/davnci-crd/StructureDefinition/CRDHookOrderSignContext"
} ]
}, {
"url": "http://hl7.org/fhir/tools/StructureDefinition/type-specifier",
"extension": [ {
"url": "condition",
"valueString": "%resource.hook = 'order-sign'"
}, {
"url": "type",
"valueCode": "http://hl7.org/fhir/us/davnci-crd/StructureDefinition/CRDHookOrderSignContext"
} ]
} ],
"mustSupport": true
}, {
"id": "CDSHooksRequest.prefetch",
"path": "CDSHooksRequest.prefetch",
"short": "Prefetch info requested by server",
"comment": "While this is mustSupport, CRD clients are not required to pass any or all prefetch data requested by the CRD service.",
"mustSupport": true
}, {
"id": "CDSHooksRequest.prefetch.key",
"path": "CDSHooksRequest.prefetch.key",
"short": "Key as specfied in server prefetch config",
"mustSupport": true
}, {
"id": "CDSHooksRequest.prefetch.value",
"path": "CDSHooksRequest.prefetch.value",
"short": "Resource(s) matching prefetch criteria",
"mustSupport": true
} ]
},
"contact": [ {
"telecom": [ {
"value": "http://www.hl7.org/Special/committees/fm",
"system": "url"
} ]
} ],
"baseDefinition": "http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest"
}