Pharmacy

Medication Request

A MedicationRequest records a prescriber's intent to supply or administer a medication to a patient — the FHIR MedicationRequest resource. You create one whenever a drug is ordered during an encounter; it carries the medication, dosage…

3.1 · versioned documentation · 10 min read

A MedicationRequest records a prescriber's intent to supply or administer a medication to a patient — the FHIR MedicationRequest resource. You create one whenever a drug is ordered during an encounter; it carries the medication, dosage instructions, timing, and route as structured JSON, grouped under a prescription.

Source:

• Model: care/emr/models/medication_request.py
• Spec: resources/medication/request/spec.py
• Spec: resources/medication/request_prescription/spec.py
• Value sets: resources/medication/valueset/

Several fields are opaque JSONFields whose structure the Django model never declares. The contract lives in the Pydantic resource specs under care/emr/resources/medication/request/: the enums, the nested shape of those JSON fields, validation rules, the read/write schema split, and the server-side side effects. The tables below merge both layers.

Models

Both extend EMRBaseModel, which supplies external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and history/meta JSON.

MedicationRequest fields

Order status & intent

Medication & dosage

Subject & provenance

Enum values

Spec enums use underscored member values (on_hold, entered_in_error, original_order), not the hyphenated FHIR spellings. These are the exact strings the API accepts and returns.

MedicationRequestStatus values

StatusReason values

MedicationRequestIntent values

MedicationRequestPriority values

MedicationRequestCategory values

MedicationRequestDispenseStatus values

TimingUnit values

UCUM time units used by Timing.repeat.period_unit and bounds_duration.unit.

DoseType values

Used by DoseAndRate.type.

DosageInstruction nested spec

Each entry in the dosage_instruction JSON list deserializes to a DosageInstruction (Pydantic, snake_case keys) — the structure hiding behind the opaque JSONField.

Sub-types under DosageInstruction

Timing {
  repeat: TimingRepeat        # required
  code: Coding | None         # e.g. BID/TID/QID timing abbreviation
}

TimingRepeat {
  frequency: int              # required — repetitions per period
  period: Decimal(20,0)       # required — duration the frequency applies to
  period_unit: TimingUnit     # required — s|min|h|d|wk|mo|a
  bounds_duration: TimingQuantity  # required — total span
}

TimingQuantity {              # integer-valued time amount
  value: Decimal(20,0)        # required
  unit: TimingUnit            # required
}

DoseAndRate {
  type: DoseType              # required — ordered | calculated
  dose_range: DoseRange | None      # for titrated doses
  dose_quantity: DosageQuantity | None  # for regular doses
}

DoseRange {
  low: DosageQuantity         # required
  high: DosageQuantity        # required
}

DosageQuantity {              # measured dose amount
  value: Decimal(20,6)        # required
  unit: Coding                # required
}

The Pydantic specs define these JSON keys as snake_case (as_needed_boolean, period_unit, dose_and_rate, max_dose_per_period, bounds_duration), so that is how they sit in storage — not the camelCase FHIR wire format.

Bound value sets

Coded fields bind to MANSOQ value sets through ValueSetBoundCoding[<slug>]. On write, the supplied Coding.code is validated against the value set; a code outside it is rejected. All draw from SNOMED CT (http://snomed.info/sct).

system-medication-not-given lives in this directory too, but it binds on Medication Administration, not on the request.

Resource specs (API schema)

Every spec extends EMRResource, which provides serialize / de_serialize plus the perform_extra_serialization / perform_extra_deserialization hooks. MedicationRequestResource sets __exclude__ = [patient, encounter, requester, requested_product, prescription], so those relations are wired up by hand instead of auto-mapped.

Validation (create — MedicationRequestSpec)

• Medication XOR product: you cannot set both medication and requested_product, and one is required.
• Prescription XOR create: you cannot set both prescription and create_prescription.
• Encounter existence: the encounter UUID must match an existing Encounter (field validator).
• authored_on, and any nested PeriodSpec/timing datetimes, must be timezone-aware.

Server-side side effects (perform_extra_deserialization)

• encounter is resolved from its UUID, then patient is copied from encounter.patient — the client never sets patient directly.
• requester / requested_product are resolved by external_id. If requested_product.facility is set and differs from encounter.facility, the write raises "Product not found in facility".
• prescription is resolved by external_id, scoped to the same encounter.
• create_prescription looks up an existing prescription by (alternate_identifier, encounter). A match that is not active raises "Prescription is not active"; no match creates a new MedicationRequestPrescription (status=active, copying name/note, prescribed_by=requester) and links the request to it.

Serialization (read)

perform_extra_serialization sets id = external_id and expands requested_product, requester, and the audit users (created_by/updated_by) from cache. MedicationRequestReadSpec goes further, expanding prescription and emitting encounter as its external id.

Related models

MedicationRequestPrescription

The container that groups every medication request authored together for an encounter into one prescription. Each request points back via MedicationRequest.prescription.

encounter            → FK Encounter (CASCADE)
patient              → FK Patient (CASCADE)
name                 → CharField(100), nullable
note                 → TextField, nullable
prescribed_by        → FK users.User (CASCADE, nullable)
status               → CharField(100), nullable  → MedicationRequestPrescriptionStatus
approval_status      → CharField(100), nullable
alternate_identifier → CharField(100), nullable
tags                 → ArrayField[int], default []

A UniqueConstraint (unique_alternate_identifier_encounter) keeps alternate_identifier unique per encounter.

MedicationRequestPrescriptionStatus values

active, on_hold, ended, stopped, completed, cancelled, entered_in_error, draft.

A pharmacist may only move a prescription between active, on_hold, completed (MEDICATION_PRESCRIPTION_PHARMACIST_ALLOWED_STATUS).

Prescription specs

Methods & save behaviour

• Read and write run through the inherited EMRResource.serialize / de_serialize. de_serialize dumps with exclude_defaults=True, maps the remaining fields onto the model, then calls perform_extra_deserialization for the relation and prescription handling above.
• patient always comes from encounter; the client never writes it.
• Inline prescription creation (create_prescription) is idempotent on (alternate_identifier, encounter) and proceeds only when an existing match is active.
• authored_on falls back to timezone.now at the model layer when omitted.

API integration notes

• Coded fields take a single Coding object { system, code, display } validated against bound SNOMED CT value sets — send a code from the right value set or the write fails.
• Enum members are underscored (on_hold, entered_in_error, original_order); send those literals, not the FHIR hyphenated forms.
• dosage_instruction carries SIG text, timing/frequency, PRN flags, dose and rate, and max-dose limits — write the full nested shape (snake_case keys) rather than free text alone.
• On create, send either medication or requested_product (not both) and at most one of prescription / create_prescription.
• Updates reach only status, note, and dispense_status.
• requester, requested_product, and prescription use SET_NULL, so a request outlives the user, product, or prescription it referenced.

Related

• Reference: Medication Administration
• Reference: Medication Dispense
• Reference: Medication Statement
• Reference: Product Knowledge
• Reference: Encounter
• Reference: Patient
• Reference: Base Model
• Source: medication_request.py · request/spec.py · request_prescription/spec.py

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/medications/medication-request.mdx:1 · f6e9f05f