QuestionnaireResponse Profile

Canonical	../StructureDefinition/nexus-emr-core-questionnaireresponse
Status	draft (experimental) · 1.26.0
Base	QuestionnaireResponse (constraint)
Source	FSH · JSON

Nexus EMR profile for QuestionnaireResponse -- completed intake, screening and consent forms, including those passed through from external eReferral partners. Appears in the patient chart's journey timeline. First pass: dating and form linkage; item structure is deliberately unconstrained.

FSH

The authored source of truth: resources/StructureDefinition-nexus-emr-core-questionnaireresponse.fsh (edit on GitHub). One FSH file may define several related artifacts.

// NexusEmrCoreQuestionnaireResponse.fsh
// FIRST PASS. Completed forms -- intake questionnaires, screening instruments, consent
// questionnaires -- as they appear in the patient chart.
//
// Why this profile exists, and why it escalated. QuestionnaireResponse began as external
// eReferral pass-through, where "the IG could just document pass-through" was a defensible
// answer. It is no longer only that: the chart's own journey/timeline registers a
// `questionnaire` category on `resourceType: "QuestionnaireResponse"`, dated by `.authored`,
// and publishes it in the chart's fetch fan-out. That is WELL-INTERNAL operational
// consumption -- the patient chart's own timeline -- which is the strongest un-modeled-surface
// class. The chart is shipping a category the IG cannot describe.
//
// Three concrete consequences of having no profile, all of which this first pass addresses:
//   - `authored` is 0..1 in R4, so an undated response silently drops out of the timeline;
//   - with no EffectiveDate declaration the facade accessor and the PatientCache windows
//     cannot date it at all, so it can never join any other date-driven chart surface
//     consistently;
//   - with no identifier contract there is no governed way to link a response back to the
//     source-EMR form it came from.
//
// FIRST-PASS SCOPE. Skeleton, dating, and the linkage back to the form definition.
// Deliberately NOT settled: whether `item` structure is constrained at all -- external
// instruments define their own trees and constraining them would break pass-through.
//
// Two things this header listed as unsettled are settled as of 1.20.0, by the Questionnaire
// profile rather than by this one: `questionnaire` now has a governed target for a form
// authored here, and how an answer that is also a clinical fact becomes an Observation is a
// property of the form (contained prototypes named by SDC's `templateExtract`) rather than an
// undecided convention. See NexusEmrCoreQuestionnaire.

Alias: $NexusEmrCoreQuestionnaireResponse = ../StructureDefinition/nexus-emr-core-questionnaireresponse

// Dating rule. `authored` is the only date this resource has, the chart's journey timeline
// dates entries by it, and it is optional in R4 -- so an undated response is silently
// invisible rather than visibly broken.
Invariant:     questionnaireresponse-has-authored
Description:   "SHOULD carry `authored` -- it is the only date this resource has, and the chart timeline drops undated responses silently"
Severity:      #warning
Expression:    "authored.exists()"

// Profile Definition
Profile:        NexusEmrCoreQuestionnaireResponse
Parent:         QuestionnaireResponse
Id:             nexus-emr-core-questionnaireresponse
Title:          "QuestionnaireResponse Profile"
Description:    "Nexus EMR profile for QuestionnaireResponse -- completed intake, screening and consent forms, including those passed through from external eReferral partners. Appears in the patient chart's journey timeline. First pass: dating and form linkage; item structure is deliberately unconstrained."
// Exposed to SMART apps, and read-only. The chart's journey timeline publishes this type, so an
// app loading a chart reads it as a matter of course -- while Questionnaire, the blank form, was
// exposed and the answers to it were not, which made a wildcard read return every form definition
// and none of the responses. Read alone because nothing writes one through this surface: a
// response authored elsewhere arrives on the eReferral message flow, not as a third-party create,
// so write and delete would grant reach no consumer has asked for.
* insert SmartExposedReadOnly(questionnaireresponse)
* ^url = $NexusEmrCoreQuestionnaireResponse // Canonical URL from alias
* ^status = #draft
* ^experimental = true
* obeys questionnaireresponse-has-authored

* . ^short      = "Nexus EMR QuestionnaireResponse Core"
* . ^definition = """
  A completed form for a patient: intake questionnaire, screening instrument, or consent
  questionnaire. May be authored in this EMR or received from an external partner. Surfaces in
  the patient chart's journey timeline as a `questionnaire` entry.
  """

// THE effective date for this profile: `authored`, and there is no fallback -- this resource
// has exactly one date. Declaring it is the fix for the chart being unable to date the
// category it already renders.
* insert EffectiveDate([[authored]])

* insert Salient(status, status, code)
* insert Salient(date, authored, dateTime)


* meta.source 0..1 MS
* meta.source ^short = "Identifies EMR instance & pipeline version the resource came from"
* meta.source ^definition = "A URI that identifies the EMR pipeline and version from which this resource originated.  This tells you which EMR instance (recommend using the instance identifier), and the version of the pipeline code/transformations."

* text 0..1 MS // Narrative element with human-readable summary
* text ^short = "Narrative"
* text ^definition = "A human-readable narrative summary of the NexusEmrCoreQuestionnaireResponse resource for human interpretation."

// NOT Must Support, and the reason is that nothing mints one. `identifier` here is
// RECOMMENDED but not required, under no mandated system -- and since the instance-scoped
// scheme was retired (FHIR-71) no producer writes a business identifier onto this type at
// all. Must Support asserts that an implementer can be expected to populate an element;
// claiming it for one the specification neither mandates nor produces states a guarantee
// that is not being made. The element stays available and documented -- a writer with a
// source-system identifier should still carry it.
* identifier 0..1
* identifier.system 1..1
* identifier.value 1..1
* identifier ^short = "Business identifier for the response"
* identifier ^definition = """
The source-system identifier for this completed form. Note this element is 0..1 in R4 -- a single identifier, not an array, unlike most resources in this IG.

This is the only governed way to link a response back to the form instance it came from in the originating EMR or partner system.

If no recognized system exists, implementers MAY invent a URI for the system.
"""
* insert SourceIdentifier(identifier)

* status 1..1 MS
* status ^short = "Where the response is in its lifecycle"
* status ^comment = "Chart surfaces SHOULD scope to `completed` and `amended`. An `in-progress` response is a partially-filled form and rendering it as a chart fact overstates it."

// -----------------------------------------
// Questionnaire -- which form this answers
// -----------------------------------------
* questionnaire 0..1 MS
* questionnaire ^short = "Canonical URL of the form definition this answers"
* questionnaire ^comment = "For an EXTERNAL instrument this is a canonical reference to a definition the IG does not govern, which is correct and permanent. For a WELL-authored form it now resolves to a NexusEmrCoreQuestionnaire -- the gap this comment used to describe was closed in 1.20.0. A response with no `questionnaire` still cannot be interpreted beyond its own display text, because nothing states what the items mean."

* subject 0..1 MS
* subject ^short = "The patient the form is about"
* subject only Reference(NexusEmrCorePatient)
* subject ^comment = "0..1 per R4. Anything appearing in a patient chart MUST carry it -- an unsubjected response cannot be scoped to (or excluded from) a chart."

* encounter 0..1 MS
* encounter ^short = "The encounter during which the form was completed"
* encounter only Reference(NexusEmrCoreEncounter)
* encounter ^comment = "Encounter is the association anchor for resources arising from a visit -- see the Encounter profile's appointment/encounter model."

* authored 0..1 MS
* authored ^short = "When the form was completed"
* authored ^comment = "THE effective date for this profile. Optional in R4 and left optional here (pass-through responses may genuinely lack it), but see questionnaireresponse-has-authored: an undated response is invisible to the timeline rather than visibly incomplete."

* author 0..1 MS
* author ^short = "Who recorded the answers"
* author only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or NexusEmrCorePatient or NexusEmrCoreRelatedPerson or NexusEmrCoreAppDevice)
* author ^comment = "Distinct from `source` (who the answers are about / who supplied them). A patient-completed intake form has Patient as source; the author may be the same Patient (self-serve portal) or a staff member transcribing."

* source 0..1 MS
* source ^short = "Who supplied the answers"
* source only Reference(NexusEmrCorePatient or NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or NexusEmrCoreRelatedPerson)

// -----------------------------------------
// Item -- DELIBERATELY UNCONSTRAINED
// -----------------------------------------
* item 0..* MS
* item ^short = "The answered questions (structure intentionally unconstrained)"
* item ^comment = "Deliberately unconstrained, not an oversight, and the asymmetry with NexusEmrCoreQuestionnaire is deliberate too: a RESPONSE may arrive from an external instrument whose tree we do not govern, so constraining it would make conformant partner data non-conformant, whereas a form DEFINITION in Nexus is one we authored or translated inward and IS constrained. Consumers MUST treat the item tree as open: recurse rather than index positionally, tolerate nested `item` at any depth (a real intake form reaches six levels), and expect `answer.value[x]` in any of its permitted types."