Huli FHIR Core Implementation Guide (R5) - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Appointment Mapping

Appointment Mapping (R5)

HuliAppointment profiles the FHIR R5 Appointment resource, including the native R5 recurring-series surface.

Huli source	FHIR element
time_slot lower/upper	start / end
appointment_status_lkp.fhir_code	status
org service UUID	serviceType.concept.coding (R5 CodeableReference)
appointment_type_lkp (SNOMED)	appointmentType (server-derived)
(not exposed — D-008)	staff-only operational notes are never surfaced through comment or note[]
patient_instruction	patientInstruction
id_confirmation_status	extension[confirmationStatus]
created_by / modified_by	extension[createdBy] / extension[modifiedBy]
cancellation audit	cancellationReason + extension[cancellationInfo]
series patient	subject

Recurring series (R5)

A recurring booking is a master Appointment carrying a recurrenceTemplate (timezone + recurrenceType CodeableConcept + occurrenceDate first date + weekly/monthly/yearly template). Occurrences carry a 1-based recurrenceId.

_recurrenceScope query parameter

Mutations on an occurrence select scope via _recurrenceScope:

• this (default) — the single targeted occurrence.
• this-and-following — the targeted occurrence and every later one.
• all — the entire series (occurrences + master template).

A PUT /fhir/R5/Appointment/{id}?_recurrenceScope=<scope> with status = cancelled cancels the selected occurrences; a PUT with any other status applies the edit to the same set. There is no REST delete on this API.

The all scope edits series metadata only — description, patientInstruction, serviceType, specialty, status, and priority — across every occurrence. Because a PUT is a full representation, its body always carries start/end (and may carry participants), but an all-scope edit cannot move every occurrence to one absolute time. The server therefore compares the submitted start/end and participant set against the targeted occurrence's current values: when they match (a metadata-only edit that merely re-sends the current timing), the metadata diff is applied across the series; when they differ (a real reschedule or participant change), the request is rejected with a 400 (HPB-00101) so the timing change is never silently dropped. To reschedule or re-staff occurrences, use this or this-and-following, which do accept start/ end and participant changes.

A this-and-following edit splits the series: the original pattern is bounded just before the targeted occurrence, the targeted-and-later occurrences are cancelled, and a new pattern re-materializes them with the edit applied. The response body is the representative occurrence of the new series — its id differs from the id the PUT targeted (which is now a cancelled occurrence of the old series). Follow the returned resource (and its recurrence-pattern-id extension on a subsequent GET) rather than the original id. The split preserves the series' original bound: an occurrenceCount counts across both halves, and a lastOccurrenceDate carries over unchanged.

R5 has no originalSubject element — the series subject rides the standard Appointment.subject.