CDSHooksRequest
type: StructureDefinition
node role: treeRoot
id:
  v: CDSHooksRequest
text:
  status:
    v: extensions
  div: English Generated Narrative: StructureDefinition CDSHooksRequest Name Flags Card. Type Description & Constraints<img src="[binary]" alt="doco" style="background-color: inherit"/> CDSHooksRequest C 0..* CDSHooksElement Elements defined in Ancestors:extension The response to the discovery endpoint Constraints: cds-r-1 #xD; hook 1..1 code The hook that triggered this CDS Service call #xD; hookInstance 1..1 uuid A universally unique identifier (UUID) for this particular hook call When this element is read urn:uuid: is prefixed to the value before validation #xD; fhirServer 0..1 url The base URL of the CDS Client's FHIR server #xD; fhirAuthorization C 0..1 CDSHooksElement 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 Constraints: cds-r-2 #xD; accessToken 1..1 string This is the OAuth 2.0 access token that provides access to the FHIR server JSON Property Name: access_token #xD; tokenType 1..1 code Fixed value: Bearer JSON Property Name: token_type Fixed Value: Bearer #xD; expiresIn 1..1 integer The lifetime in seconds of the access token. JSON Property Name: expires_in #xD; scope 1..1 string The scopes the access token grants the CDS Service #xD; subject 1..1 string The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server #xD; patient 0..1 id The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server #xD; context 1..1 CDSHookContext Hook-specific contextual data that the CDS service will need JSON: If%resource.hook = 'patient-view'then the type is CDSHookPatientViewContext JSON: If%resource.hook = 'order-sign'then the type is CDSHookOrderSignContext JSON: If%resource.hook = 'order-select'then the type is CDSHookOrderSelectContext #xD; prefetch 0..* Base Key/value pairs of FHIR queries the CDS Client provides on each call JSON: Represented as a single JSON Ob…
extension:
  url:
    v: http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm
  value: integer
    v: 1
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-suppress-resourcetype
  value: boolean
    v: true
extension:
  url:
    v: http://hl7.org/fhir/StructureDefinition/structuredefinition-wg
  value: code
    v: fhir
extension:
  url:
    v: http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status
  value: code
    v: informative
    extension:
      url:
        v: http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom
      value: canonical
        v: http://hl7.org/fhir/tools/ImplementationGuide/hl7.fhir.uv.tools
        link: http://hl7.org/fhir/tools/ImplementationGuide/hl7.fhir.uv.tools
url:
  v: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest
identifier:
  system:
    v: urn:ietf:rfc:3986
  value:
    v: urn:oid:2.16.840.1.113883.4.642.40.1.42.6
version:
  v: 0.6.0
name:
  v: CDSHooksRequest
title:
  v: CDSHooks Request (Logical Definition)
status:
  v: draft
experimental:
  v: true
date:
  v: 2025-07-20T21:15:46+10:00
publisher:
  v: HL7 International / FHIR Infrastructure
contact:
  telecom:
    system:
      v: url
    value:
      v: http://www.hl7.org/Special/committees/fiwg
description:
  v: 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
jurisdiction:
  coding:
    system:
      v: http://unstats.un.org/unsd/methods/m49/m49.htm
    code:
      v: 001
fhir version:
  v: 5.0.0
mapping:
  identity:
    v: rim
  uri:
    v: http://hl7.org/v3
  name:
    v: RIM Mapping
kind:
  v: logical
abstract:
  v: false
type:
  v: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksRequest
base definition:
  v: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement
  link: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement
derivation:
  v: specialization
snapshot:
  extension:
    url:
      v: http://hl7.org/fhir/tools/StructureDefinition/snapshot-base-version
    value: string
      v: 0.6.0
  element:
    id:
      v: CDSHooksRequest
    path:
      v: CDSHooksRequest
    short:
      v: The response to the discovery endpoint
    definition:
      v: The response to the discovery endpoint
    min:
      v: 0
    max:
      v: *
    base:
      path:
        v: Base
      min:
        v: 0
      max:
        v: *
    constraint:
      key:
        v: cds-r-1
      severity:
        v: error
      human:
        v: if fhirAuthorization details are provided, a fhirServer SHALL be specified
      expression:
        v: fhirAuthorization.exists() implies fhirServer.exists()
    is modifier:
      v: false
    mapping:
      identity:
        v: rim
      map:
        v: n/a
  element:
    id:
      v: CDSHooksRequest.extension
    path:
      v: CDSHooksRequest.extension
    short:
      v: Object that has Named Extension Properties
    definition:
      v: A JSON object that has properties where the names are defined by the extension definitions
    comment:
      v: 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
    min:
      v: 0
    max:
      v: 1
    base:
      path:
        v: CDSHooksElement.extension
      min:
        v: 0
      max:
        v: 1
    type:
      code:
        v: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksExtensions
  element:
    id:
      v: CDSHooksRequest.hook
    path:
      v: CDSHooksRequest.hook
    short:
      v: The hook that triggered this CDS Service call
    definition:
      v: The hook that triggered this CDS Service call
    min:
      v: 1
    max:
      v: 1
    base:
      path:
        v: CDSHooksRequest.hook
      min:
        v: 1
      max:
        v: 1
    type:
      code:
        v: code
  element:
    id:
      v: CDSHooksRequest.hookInstance
    extension:
      url:
        v: http://hl7.org/fhir/tools/StructureDefinition/implied-string-prefix
      value: string
        v: urn:uuid:
    path:
      v: CDSHooksRequest.hookInstance
    short:
      v: A universally unique identifier (UUID) for this particular hook call
    definition:
      v: 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
    comment:
      v: Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable.
    min:
      v: 1
    max:
      v: 1
    base:
      path:
        v: CDSHooksRequest.hookInstance
      min:
        v: 1

v: 1

code:
  v: uuid

id:
  v: CDSHooksRequest.fhirServer
path:
  v: CDSHooksRequest.fhirServer
short:
  v: The base URL of the CDS Client's FHIR server
definition:
  v: 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
min:
  v: 0
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirServer
  min:
    v: 0
  max:
    v: 1
type:
  code:
    v: url

id:
  v: CDSHooksRequest.fhirAuthorization
path:
  v: CDSHooksRequest.fhirAuthorization
short:
  v: 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
definition:
  v: 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
min:
  v: 0
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirAuthorization
  min:
    v: 0
  max:
    v: 1
type:
  code:
    v: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement
constraint:
  key:
    v: cds-r-2
  severity:
    v: error
  human:
    v: 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.
  expression:
    v: scope.contains('Patient/') implies patient.exists()

id:
  v: CDSHooksRequest.fhirAuthorization.extension
path:
  v: CDSHooksRequest.fhirAuthorization.extension
short:
  v: Object that has Named Extension Properties
definition:
  v: A JSON object that has properties where the names are defined by the extension definitions
comment:
  v: 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
min:
  v: 0
max:
  v: 1
base:
  path:
    v: CDSHooksElement.extension
  min:
    v: 0
  max:
    v: 1
type:
  code:
    v: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksExtensions

id:
  v: CDSHooksRequest.fhirAuthorization.accessToken
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-name
  value: string
    v: access_token
path:
  v: CDSHooksRequest.fhirAuthorization.accessToken
short:
  v: This is the OAuth 2.0 access token that provides access to the FHIR server
definition:
  v: This is the OAuth 2.0 access token that provides access to the FHIR server
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirAuthorization.accessToken
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: string

id:
  v: CDSHooksRequest.fhirAuthorization.tokenType
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-name
  value: string
    v: token_type
path:
  v: CDSHooksRequest.fhirAuthorization.tokenType
short:
  v: Fixed value: Bearer
definition:
  v: Fixed value: Bearer
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirAuthorization.tokenType
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: code
fixed: code
  v: Bearer

id:
  v: CDSHooksRequest.fhirAuthorization.expiresIn
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-name
  value: string
    v: expires_in
path:
  v: CDSHooksRequest.fhirAuthorization.expiresIn
short:
  v: The lifetime in seconds of the access token.
definition:
  v: The lifetime in seconds of the access token.
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirAuthorization.expiresIn
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: integer

id:
  v: CDSHooksRequest.fhirAuthorization.scope
path:
  v: CDSHooksRequest.fhirAuthorization.scope
short:
  v: The scopes the access token grants the CDS Service
definition:
  v: The scopes the access token grants the CDS Service
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirAuthorization.scope
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: string

id:
  v: CDSHooksRequest.fhirAuthorization.subject
path:
  v: CDSHooksRequest.fhirAuthorization.subject
short:
  v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server
definition:
  v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirAuthorization.subject
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: string

id:
  v: CDSHooksRequest.fhirAuthorization.patient
path:
  v: CDSHooksRequest.fhirAuthorization.patient
short:
  v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server
definition:
  v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server
min:
  v: 0
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.fhirAuthorization.patient
  min:
    v: 0
  max:
    v: 1
type:
  code:
    v: id

id:
  v: CDSHooksRequest.context
extension:
  extension:
    url:
      v: condition
    value: string
      v: %resource.hook = 'patient-view'
  extension:
    url:
      v: type
    value: code
      v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookPatientViewContext
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/type-specifier
extension:
  extension:
    url:
      v: condition
    value: string
      v: %resource.hook = 'order-sign'
  extension:
    url:
      v: type
    value: code
      v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSignContext
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/type-specifier
extension:
  extension:
    url:
      v: condition
    value: string
      v: %resource.hook = 'order-select'
  extension:
    url:
      v: type
    value: code
      v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSelectContext
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/type-specifier
path:
  v: CDSHooksRequest.context
short:
  v: Hook-specific contextual data that the CDS service will need
definition:
  v: Hook-specific contextual data that the CDS service will need
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.context
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookContext

id:
  v: CDSHooksRequest.prefetch
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-property-key
  value: code
    v: key
path:
  v: CDSHooksRequest.prefetch
short:
  v: Key/value pairs of FHIR queries the CDS Client provides on each call
definition:
  v: 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
min:
  v: 0
max:
  v: *
base:
  path:
    v: CDSHooksRequest.prefetch
  min:
    v: 0
  max:
    v: *
type:
  code:
    v: Base

id:
  v: CDSHooksRequest.prefetch.key
path:
  v: CDSHooksRequest.prefetch.key
short:
  v: Key of FHIR query - name for client to use when sending to Request
definition:
  v: Key of FHIR query - name for client to use when sending to Request
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.prefetch.key
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: code

id:
  v: CDSHooksRequest.prefetch.value
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-nullable
  value: boolean
    v: true
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/id-expectation
  value: code
    v: optional
path:
  v: CDSHooksRequest.prefetch.value
short:
  v: Value of FHIR query - FHIR Query for client to perform
definition:
  v: Value of FHIR query - FHIR Query for client to perform
min:
  v: 1
max:
  v: 1
base:
  path:
    v: CDSHooksRequest.prefetch.value
  min:
    v: 1
  max:
    v: 1
type:
  code:
    v: Resource

element:
  id:
    v: CDSHooksRequest
  path:
    v: CDSHooksRequest
  short:
    v: The response to the discovery endpoint
  definition:
    v: The response to the discovery endpoint
  constraint:
    key:
      v: cds-r-1
    severity:
      v: error
    human:
      v: if fhirAuthorization details are provided, a fhirServer SHALL be specified
    expression:
      v: fhirAuthorization.exists() implies fhirServer.exists()
element:
  id:
    v: CDSHooksRequest.hook
  path:
    v: CDSHooksRequest.hook
  short:
    v: The hook that triggered this CDS Service call
  definition:
    v: The hook that triggered this CDS Service call
  min:
    v: 1
  max:
    v: 1
  type:
    code:
      v: code
element:
  id:
    v: CDSHooksRequest.hookInstance
  extension:
    url:
      v: http://hl7.org/fhir/tools/StructureDefinition/implied-string-prefix
    value: string
      v: urn:uuid:
  path:
    v: CDSHooksRequest.hookInstance
  short:
    v: A universally unique identifier (UUID) for this particular hook call
  definition:
    v: 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
  comment:
    v: Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable.
  min:
    v: 1
  max:
    v: 1
  type:
    code:
      v: uuid
element:
  id:
    v: CDSHooksRequest.fhirServer
  path:
    v: CDSHooksRequest.fhirServer
  short:
    v: The base URL of the CDS Client's FHIR server
  definition:
    v: 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
  min:
    v: 0
  max:
    v: 1
  type:
    code:
      v: url
element:
  id:
    v: CDSHooksRequest.fhirAuthorization
  path:
    v: CDSHooksRequest.fhirAuthorization
  short:
    v: 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
  definition:
    v: 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
  min:
    v: 0
  max:
    v: 1
  type:
    code:
      v: http://hl7.org/fhir/tools/StructureDefinition/CDSHooksElement
  constraint:
    key:
      v: cds-r-2
    severity:
      v: error
    human:
      v: 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.
    expression:
      v: scope.contains('Patient/') implies patient.exists()
element:
  id:
    v: CDSHooksRequest.fhirAuthorization.accessToken
  extension:
    url:
      v: http://hl7.org/fhir/tools/StructureDefinition/json-name
    value: string
      v: access_token
  path:
    v: CDSHooksRequest.fhirAuthorization.accessToken
  short:
    v: This is the OAuth 2.0 access token that provides access to the FHIR server
  definition:
    v: This is the OAuth 2.0 access token that provides access to the FHIR server
  min:
    v: 1
  max:
    v: 1
  type:
    code:
      v: string
element:
  id:
    v: CDSHooksRequest.fhirAuthorization.tokenType
  extension:
    url:
      v: http://hl7.org/fhir/tools/StructureDefinition/json-name
    value: string
      v: token_type
  path:
    v: CDSHooksRequest.fhirAuthorization.tokenType
  short:
    v: Fixed value: Bearer
  definition:
    v: Fixed value: Bearer
  min:
    v: 1
  max:
    v: 1
  type:
    code:
      v: code
  fixed: code
    v: Bearer
element:
  id:
    v: CDSHooksRequest.fhirAuthorization.expiresIn
  extension:
    url:
      v: http://hl7.org/fhir/tools/StructureDefinition/json-name
    value: string
      v: expires_in
  path:
    v: CDSHooksRequest.fhirAuthorization.expiresIn
  short:
    v: The lifetime in seconds of the access token.
  definition:
    v: The lifetime in seconds of the access token.
  min:
    v: 1
  max:
    v: 1
  type:
    code:
      v: integer
element:
  id:
    v: CDSHooksRequest.fhirAuthorization.scope
  path:
    v: CDSHooksRequest.fhirAuthorization.scope
  short:
    v: The scopes the access token grants the CDS Service
  definition:
    v: The scopes the access token grants the CDS Service
  min:
    v: 1
  max:
    v: 1
  type:
    code:
      v: string
element:
  id:
    v: CDSHooksRequest.fhirAuthorization.subject
  path:
    v: CDSHooksRequest.fhirAuthorization.subject
  short:
    v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server
  definition:
    v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server
  min:
    v: 1
  max:
    v: 1
  type:
    code:
      v: string
element:
  id:
    v: CDSHooksRequest.fhirAuthorization.patient
  path:
    v: CDSHooksRequest.fhirAuthorization.patient
  short:
    v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server

v: The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server

v: 0

v: 1

code:
  v: id

id:
  v: CDSHooksRequest.context
extension:
  extension:
    url:
      v: condition
    value: string
      v: %resource.hook = 'patient-view'
  extension:
    url:
      v: type
    value: code
      v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookPatientViewContext
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/type-specifier
extension:
  extension:
    url:
      v: condition
    value: string
      v: %resource.hook = 'order-sign'
  extension:
    url:
      v: type
    value: code
      v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSignContext
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/type-specifier
extension:
  extension:
    url:
      v: condition
    value: string
      v: %resource.hook = 'order-select'
  extension:
    url:
      v: type
    value: code
      v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookOrderSelectContext
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/type-specifier
path:
  v: CDSHooksRequest.context
short:
  v: Hook-specific contextual data that the CDS service will need
definition:
  v: Hook-specific contextual data that the CDS service will need
min:
  v: 1
max:
  v: 1
type:
  code:
    v: http://hl7.org/fhir/tools/StructureDefinition/CDSHookContext

id:
  v: CDSHooksRequest.prefetch
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-property-key
  value: code
    v: key
path:
  v: CDSHooksRequest.prefetch
short:
  v: Key/value pairs of FHIR queries the CDS Client provides on each call
definition:
  v: 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
min:
  v: 0
max:
  v: *
type:
  code:
    v: Base

id:
  v: CDSHooksRequest.prefetch.key
path:
  v: CDSHooksRequest.prefetch.key
short:
  v: Key of FHIR query - name for client to use when sending to Request
definition:
  v: Key of FHIR query - name for client to use when sending to Request
min:
  v: 1
max:
  v: 1
type:
  code:
    v: code

id:
  v: CDSHooksRequest.prefetch.value
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/json-nullable
  value: boolean
    v: true
extension:
  url:
    v: http://hl7.org/fhir/tools/StructureDefinition/id-expectation
  value: code
    v: optional
path:
  v: CDSHooksRequest.prefetch.value
short:
  v: Value of FHIR query - FHIR Query for client to perform
definition:
  v: Value of FHIR query - FHIR Query for client to perform
min:
  v: 1
max:
  v: 1
type:
  code:
    v: Resource