Huli FHIR Core Implementation Guide (R4)
0.1.0 - Release
Huli FHIR Core Implementation Guide (R4) - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
HuliMedicationRequest carries a prescribed medication (a single drug line of a
prescription) recorded against a Huli patient. The Public API supports read,
search, create, and update for this resource. This surface is the FHIR projection
of the clinical Plan section ("Plan / Medicamentos") of an encounter.
Create and update both route through the same practice medication service the Huli application uses, so a public write runs the platform's clinical rules rather than writing straight to the database:
subject) and, when present, the encounter
(encounter) inside the authenticated organization; cross-organization references
are rejected with 422.409 Conflict), matching the
in-app behavior.groupIdentifier (see
Grouping and draft state).medicationCodeableConcept; client-supplied free text is honored.PUT /fhir/R4/MedicationRequest/{id} is a read-then-merge update, not a blind
replace: the FHIR-owned fields (status, the medication coding/display, and the
prescription dosage / dispense / reason / notes) overlay the stored row, while
app-only fields the FHIR projection does not carry are preserved — the
prescription warnings, the validity window, the in-prescription sort order, and
the draft-prescription grouping all survive the update. A MedicationRequest whose
parent prescription is already signed or cancelled cannot be modified
(409 Conflict), matching the in-app immutability rule. subject is immutable:
a body whose subject differs from the stored patient is rejected (422).
Every operation requires the SMART scope system/MedicationRequest.rs (read /
search) or system/MedicationRequest.cru (create / read / update) AND the
corresponding practice permission on the api key's user. A valid scope on a key
whose user lacks the permission is denied with 403.
MedicationRequest is clinical-sensitive and therefore BAA-gated: an
api key without an executed Business Associate Agreement cannot obtain these
scopes. See Data handling and compliance
for the integrator BAA obligations.
| Huli field | FHIR path | Cardinality | Must Support | Notes |
|---|---|---|---|---|
id_medication |
MedicationRequest.id |
1..1 | – | UUID, allocated server-side; client-supplied IDs are rejected on POST |
modified_on |
MedicationRequest.meta.lastUpdated |
0..1 | – | Set by the platform |
| – | MedicationRequest.meta.profile[0] |
0..1 | – | Always https://fhir.huli.ai/r4/StructureDefinition/HuliMedicationRequest |
| prescription id | MedicationRequest.groupIdentifier |
0..1 | Yes | The draft prescription the medication is grouped into (see below) |
| Huli concept | FHIR MedicationRequest.status |
Notes |
|---|---|---|
| active | active |
Default for a newly prescribed medication |
| on hold | on-hold |
Temporarily suspended |
| completed | completed |
Course finished |
| cancelled | cancelled |
Withdrawn before completion |
| entered in error | entered-in-error |
Void marker |
On write, status defaults to active when omitted. draft and stopped are
also accepted (the Huli model represents them). Only unknown is rejected with
422 at MedicationRequest.status — every other FHIR R4 status value is
accepted. (Note: unlike ServiceRequest, FHIR R4 MedicationRequest.status
DOES include cancelled.)
| FHIR path | Cardinality | Notes |
|---|---|---|
MedicationRequest.intent |
1..1 | Always emitted as order. The Public API does not model proposal / plan / option. |
Any intent is accepted and normalized to order on write — it is not rejected.
| FHIR path | Notes |
|---|---|
MedicationRequest.medicationCodeableConcept.text |
Medication name (free text); required on write |
MedicationRequest.medicationCodeableConcept.coding[0].code |
Medication code, when the medication is catalog-coded |
MedicationRequest.medicationCodeableConcept.coding[0].display |
Display string mirroring the medication name |
medicationReference is not supported — the Public API carries the
medication inline as a CodeableConcept only.
| FHIR path | Cardinality | Must Support | Notes |
|---|---|---|---|
MedicationRequest.subject |
1..1 | Yes | Reference(HuliPatient); required on read and write |
MedicationRequest.encounter |
0..1 | Yes | Reference(HuliEncounter); the encounter the medication was prescribed in |
MedicationRequest.requester |
0..1 | – | Reference(Practitioner); server-stamped as the authenticated user on write — a client-supplied requester is not honored as the prescriber |
References passed on create must resolve inside the authenticated organization;
cross-organization references are rejected with 422.
The dosage is carried by a single dosageInstruction[0] entry. The Public API
emits and accepts a flat dosage shape (see
Parity limitations).
| FHIR path | Huli concept | Notes |
|---|---|---|
dosageInstruction[0].text |
Free-text dosage | The human-readable dosage line, always emitted |
dosageInstruction[0].timing.repeat.frequency |
Frequency | Times per period |
dosageInstruction[0].timing.repeat.period |
Period | Length of the period |
dosageInstruction[0].timing.repeat.periodUnit |
Period unit | UCUM-style time unit (h, d, …) |
dosageInstruction[0].timing.repeat.when[0] |
When | Event timing code (e.g. AC, PC, HS) |
dosageInstruction[0].doseAndRate[0].doseQuantity.value |
Dose value | Numeric dose |
dosageInstruction[0].doseAndRate[0].doseQuantity.unit |
Dose unit | Display unit |
dosageInstruction[0].route.coding[0] / .text |
Route | Route of administration |
dosageInstruction[0].asNeededBoolean |
As needed (PRN) | true when the medication is taken as needed |
| FHIR path | Huli concept | Notes |
|---|---|---|
dispenseRequest.quantity.value / .unit |
Quantity to dispense | Amount and unit to be dispensed |
dispenseRequest.expectedSupplyDuration.value |
Expected supply duration | Days/period of supply, when recorded |
| FHIR path | Huli concept | Notes |
|---|---|---|
MedicationRequest.reasonCode[0].text |
Reason | Free-text indication for the medication |
MedicationRequest.note[0].text |
Notes | Free-text prescriber notes |
A medication created over FHIR is not a standalone artifact in the Huli
model — it is a line item of a prescription. On create, the API attaches the new
medication to the patient's open draft prescription (creating one if none is
open), and returns that prescription id as MedicationRequest.groupIdentifier.
Multiple medications created against the same patient/encounter while a draft is
open share the same groupIdentifier, so a client can reconstruct the
prescription grouping from the responses.
The prescription is created in an unsigned draft state — the FHIR write surface does not sign/finalize the prescription. Signing remains an in-app action (see Parity limitations).
The Public API advertises the following search parameters on
GET /fhir/R4/MedicationRequest:
| Parameter | Type | Notes |
|---|---|---|
_id |
token | Direct lookup by MedicationRequest.id |
patient |
reference | Reference(HuliPatient); logical id or full reference |
encounter |
reference | Reference(HuliEncounter) |
_count |
number | Page size |
_cursor |
string | Opaque cursor returned in Bundle.link[rel=next] |
A patient or encounter parameter is required. status and code are
not search parameters in v1 — the search filters by patient/encounter only.
Search responses are returned as a FHIR Bundle of type searchset with
cursor-based pagination.
dosageInstruction[0] is emitted/consumed. Multi-line dosing (tapering
schedules, dosageInstruction[1..n]) is not supported — extra entries on write
are rejected with 400.medicationReference. The medication is carried inline as a
CodeableConcept; a medicationReference to a contained or external
Medication resource is not supported.| Huli concept | Reason it is not on MedicationRequest |
|---|---|
| Prescription signature / sign state | The FHIR surface creates unsigned drafts only (see above) |
| Prescription print/PDF rendering | Operational artifact; not part of the resource contract |
| Prescriber license / credential block | Carried on Practitioner, not on the medication line |