Medication Dispense Profile

Canonical	../StructureDefinition/nexus-emr-core-medicationdispense
Status	draft · 1.26.0
Base	MedicationDispense (constraint)
Source	FSH · JSON

Nexus EMR profile for MedicationDispense resources, primarily for recording dispense events. Aligns with CII N1/N2 requirements and Nexus EMR standards.

FSH

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

// NexusEmrCoreMedicationDispense.fsh 

Alias: $NexusEmrCoreMedicationDispense = ../StructureDefinition/nexus-emr-core-medicationdispense


Profile:        NexusEmrCoreMedicationDispense
Parent:         MedicationDispense
Id:             nexus-emr-core-medicationdispense
Title:          "Medication Dispense Profile"
Description:    "Nexus EMR profile for MedicationDispense resources, primarily for recording dispense events. Aligns with CII N1/N2 requirements and Nexus EMR standards."
// THE effective date for this profile (see the EffectiveDate / NoEffectiveDate
// RuleSets): one date concept per resource, declared here rather than guessed.
* insert EffectiveDate([[whenHandedOver | whenPrepared]])

// Salient fields -- the reader/render surface (see SalientField + the Salient RuleSet). Same
// shape as MedicationRequest where the two overlap, plus the two values that only a dispense
// has: how much was handed over, and how long it lasts.
* insert Salient(medication, [[medicationCodeableConcept.text | medicationCodeableConcept.coding.first().display]], string)
* insert SalientComment([[Text first, then the first coding's display. `medication[x]` is constrained to CodeableConcept on this profile, so there is no reference arm to fall back to.]])
* insert Salient(status, status, code)
* insert Salient(quantity, quantity, quantity)
* insert Salient(days_supply, daysSupply, quantity)
* insert Salient(handed_over, [[whenHandedOver]], dateTime)
* insert SalientComment([[When the patient actually received the medication -- the profile's effective date, and 1..1 here. `whenPrepared` is a separate, earlier event and does not surface as a salient field.]])
* insert Salient(dosage, [[dosageInstruction.first().text]], string)
* insert SalientComment([[The FIRST dosage instruction's free text, matching MedicationRequest's `dosage`. `dosageInstruction` is 0..*; the rest stay reachable through the typed collection.]])

// SMART on FHIR exposure -- this resource is reachable by an app, and these are the
// permissions each operation costs (see SmartExposed + the SmartExposed RuleSet).
* insert SmartExposed(medicationdispense)

* ^url = $NexusEmrCoreMedicationDispense // Canonical URL alias assumed defined
* ^status = #draft
* insert NoResourceNoteExtension
* ^publisher = "WELLSTAR Technologies Corp."

// --- Element Constraints ---

* . ^short      = "Nexus EMR Medication Dispense Core"
* . ^definition = """
  Represents records of medications provided to a patient, capturing key details
  like medication, quantity, dosage, and dispensing organization using standard
  Nexus EMR references. Uses instance-specific identifiers for tracking
  medication dispense records across systems.
  """

* 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 NexusEmrCoreMedicationDispense resource for human interpretation."

// Identifier: A business identifier is recommended but not required (any system).
* identifier 0..* MS
* identifier.system 1..1
* identifier.value 1..1

* identifier ^short = "Business identifier(s) for medicationdispense"
* identifier ^definition = """
Unique identifiers for the medicationdispense.

A business identifier is recommended but not required (identifier is 0..*). Where available, carry the source-system identifier using the most appropriate system URI. No specific canonical system is mandated.

A source system's own identifier SHOULD be carried alongside this one, flagged `use = secondary`. See [Carrying the raw code](../guide/patterns/raw-codes.md).
"""


// Status: completed, entered-in-error, etc. Mandatory and MS.
* status 1..1 MS
* status ^short = "preparation | in-progress | cancelled | on-hold | completed | entered-in-error | stopped"
* status ^definition = "A code specifying the state of the dispense event."
* status ^comment = "This is a modifier element. The status affects how the dispense should be interpreted."
* status from http://hl7.org/fhir/ValueSet/medicationdispense-status (required)

// Medication: What was dispensed. Mandatory and MS. Maps to CII N1.
* medication[x] 1..1 MS
* medication[x] only CodeableConcept
* medicationCodeableConcept ^short = "Medication with raw code support"
* insert SourceCoding(medicationCodeableConcept)
* medicationCodeableConcept ^definition = """
Identifies the medication that was dispensed.

REQUIRED: text element for human readability
RECOMMENDED: an ingredient-level code whenever the source has one. CCDD is preferred; where
there is no CCDD the Health Canada DPD active-ingredient group number is the one to carry, with
ATC for class-level records. This is the level at which a dispense can be compared to the
prescription it fills, to another dispense, or to a recorded allergy.
RECOMMENDED: the DIN when the source has one, which says WHICH marketed product was handed over.
A dispense is the one place in the medication chain where the product actually matters, because
the DIN identifies what the patient physically received.
OPTIONAL: Raw EMR codes for source system preservation

RxNorm is not recommended here. It is a US drug vocabulary; Canadian sources carry DIN at the
product level and CCDD at the ingredient level, and a Canadian dispense record has no route to
an RxNorm code that does not go through a mapping this specification does not define. The
slicing is open, so a source that genuinely holds one may still carry it as an unsliced coding.

The text element ensures human readability even when coded values are not recognized.
"""
* medicationCodeableConcept.text 1..1 MS // Ensure text is present for CII N1 mapping
* medicationCodeableConcept.text ^short = "The medication as written, in human-readable form"
* medicationCodeableConcept.text ^comment = "Required."
* medicationCodeableConcept.text ^definition = "Plain text representation of the dispensed medication, required for all entries"

// Drug identity at both levels, the same model MedicationRequest and MedicationStatement carry.
// See the MedicationCoding RuleSet for what each level answers.
* insert MedicationCoding(medicationCodeableConcept)


// Subject (Patient): Who received the dispense. Mandatory and MS. Use identifier.
* subject 1..1 MS
* subject ^short = "Who the dispense is for"
* subject ^definition = "The patient who received the dispensed medication. Must reference using Nexus EMR patient identifier."
* subject ^comment = "References should use identifier-based references following Nexus EMR patterns."
* subject only Reference($NexusEmrCorePatient)

// Performer: Who performed the dispense. Optional but MS. Use identifier.
* performer 0..* MS
* performer ^short = "Who performed the dispense"
* performer ^definition = "Indicates who or what performed the dispensing event."
* performer ^comment = "May be a pharmacist, pharmacy technician, or dispensing organization."
* performer.actor 1..1 MS // Actor is required if performer is present
* performer.actor ^short = "Individual or organization who performed dispense"
* performer.actor only Reference($NexusEmrCorePractitionerRole or $NexusEmrCorePractitioner or $NexusEmrCoreOrganization)

// Authorizing Prescription: Link to the request. Optional but MS. Use identifier.
* authorizingPrescription 0..* MS
* authorizingPrescription ^short = "Prescription that authorized this dispense"
* authorizingPrescription ^definition = "Indicates the medication request that is being dispensed against."
* authorizingPrescription ^comment = "Links the dispense to the original prescription order."
* authorizingPrescription only Reference($NexusEmrCoreMedicationRequest)

// Type: Optional classification of dispense event.
* type 0..1 MS
* type ^short = "Dispense type with raw code support"
* type ^definition = """
Indicates the type of dispensing event.

RECOMMENDED: Standard terminology codes when available
OPTIONAL: Raw EMR codes for source system preservation
"""


// Category: Type of medication dispense
* category 0..1 MS
* category ^short = "Dispense category with raw code support"
* category ^definition = """
Indicates the type of medication dispense (e.g., inpatient, outpatient, community).

RECOMMENDED: Standard terminology codes when available
OPTIONAL: Raw EMR codes for source system preservation
"""


// Quantity: Amount dispensed. Optional.
* quantity 0..1
* quantity ^short = "Amount dispensed"
* quantity ^definition = "The amount of medication that has been dispensed."
* quantity ^comment = "Includes both the numerical value and the unit of measure."

// Days Supply: Optional.
* daysSupply 0..1
* daysSupply ^short = "Amount of medication for period of time"
* daysSupply ^definition = "The amount of medication expressed as a timing amount."
* daysSupply ^comment = "Typically represents the number of days the dispensed quantity will last."

// When Prepared: Optional.
* whenPrepared 0..1
* whenPrepared ^short = "When product was prepared"
* whenPrepared ^definition = "The time when the dispensed product was packaged and reviewed."
* whenPrepared ^comment = "May be different from when handed over to patient."

// When Handed Over: Date dispense occurred. Mandatory for CII N2. MS.
* whenHandedOver 1..1 MS
* whenHandedOver ^short = "When product was given - Maps to CII N2 Medication_Dispensed_Date"
* whenHandedOver ^definition = "The time the dispensed product was provided to the patient or their representative."
* whenHandedOver ^comment = "This is the actual dispense date when medication was provided to patient."

// Dosage Instruction: Optional details on administration.
* dosageInstruction 0..*
* dosageInstruction ^short = "How medication should be taken"
* dosageInstruction ^definition = "Indicates how the medication is to be used by the patient."
* dosageInstruction ^comment = "May include dose, frequency, route, and other administration instructions."

// Note: Optional comments.
* note 0..*
* note ^short = "Additional information about dispense"
* note ^definition = "Extra information about the dispense that could not be conveyed in other attributes."
* note ^comment = "May include pharmacist counseling notes or special instructions."