Appointment Modality Extension

Canonical	../StructureDefinition/nexus-emr-appointment-modality-extension
Status	draft (experimental) · 1.26.0
Base	Extension (constraint)
Context	Appointment (element)
Source	FSH · JSON

Delivery channel of an appointment/encounter (in-person | video | telephone | secure message). A distinct axis from appointmentType (booking style); R5 models this as Appointment.virtualService. Value is CodeableConcept so a source/raw code and a normalized Nexus code co-exist; the binding is extensible so a future pan-Canadian/Ontario code can be added as a parallel coding.

FSH

The authored source of truth: extensions/AppointmentModalityExtension.fsh (edit on GitHub). One FSH file may define several related artifacts.

// AppointmentModalityExtension.fsh
// Delivery channel (modality) of an appointment/encounter: in-person, video,
// telephone, secure message.
//
// Why an extension and not appointmentType: modality is a DISTINCT axis from
// Appointment.appointmentType (booking style: routine / walk-in / follow-up).
// A single CodeableConcept must carry one concept in (possibly) multiple systems,
// so modality cannot ride alongside a booking-style code on appointmentType. R5
// confirms the axis is distinct by adding a dedicated element (Appointment.
// virtualService); in R4 the idiomatic home for a new distinct axis is an extension.
//
// value[x] is CodeableConcept (house raw+normalized pattern): a source/raw modality
// code and a normalized Nexus code can co-exist as parallel codings. The binding is
// extensible, so a pan-Canadian / Ontario code may be added as a parallel coding
// when one exists, with no breaking profile change.
//
// Encounter mapping (until a machine-readable ConceptMap is warranted by a consumer):
//   in-person -> Encounter.class#AMB ; video | telephone | secure-message -> #VR
//   (http://terminology.hl7.org/CodeSystem/v3-ActCode).
//
// THIS MAPPING WAS ILLEGAL UNTIL 1.26.0, and this comment was where the conflict hid. The
// Encounter profile fixed `class` to #AMB, so the #VR half named a value no conformant Encounter
// could carry. Two published statements disagreed and an implementer could satisfy either but not
// both. The fixed value is gone; the binding governs, and the mapping is now legal as written.
//
// It also moved INTO SHIPPING TEXT, on both ends. A `//` comment renders on this page and travels
// nowhere else -- it is not in the StructureDefinition and not in package.tgz -- so the guide's
// only statement of how modality reaches an Encounter was invisible to every consumer reading the
// artifact rather than the site. That is how it stayed contradictory for as long as it did.

Extension: AppointmentModalityExtension
Id: nexus-emr-appointment-modality-extension
Title: "Appointment Modality Extension"
Description: "Delivery channel of an appointment/encounter (in-person | video | telephone | secure message). A distinct axis from appointmentType (booking style); R5 models this as Appointment.virtualService. Value is CodeableConcept so a source/raw code and a normalized Nexus code co-exist; the binding is extensible so a future pan-Canadian/Ontario code can be added as a parallel coding."
* ^url = "../StructureDefinition/nexus-emr-appointment-modality-extension"
* ^status = #draft
* ^experimental = true
* ^date = "2026-07-27"
* ^publisher = "WELLSTAR Technologies Corp."
* ^contact.name = "Nexus EMR FHIR Implementation Guide"
* ^contact.telecom.system = #url
* ^contact.telecom.value = ".."
* ^jurisdiction = urn:iso:std:iso:3166#CA "Canada"
* ^context[0].type = #element
* ^context[0].expression = "Appointment"
// Encounter context removed 2026-08-06: nothing consumes modality on Encounter, and
// contexts follow observed consumption. Re-add with evidence, not speculation.
* . ^short = "Appointment/encounter delivery channel (modality)"
* . ^definition = """
The delivery channel of the appointment or encounter: how the patient and provider
meet, as distinct from what service is delivered (serviceType) or how the slot was
booked (appointmentType).

**Mapping onto an Encounter.** Where the encounter is recorded, `in-person` becomes
`Encounter.class` `AMB`; `video`, `telephone` and `secure-message` all become `VR`
(`http://terminology.hl7.org/CodeSystem/v3-ActCode`). `Encounter.class` is bound, not
fixed, precisely so this mapping can be honoured: writing `AMB` for a video consult
asserts the visit happened in the room.

Populate the normalized coding from NexusEmrAppointmentModalityVS. When the source EMR
carries its own raw modality code (e.g. Oscar `appointment.type` = 'Telephone'),
converters SHOULD ALSO carry that raw code as an additional coding on the same
CodeableConcept, using the raw-code NamingSystem fallback
`../NamingSystem/<instance-id>-appointment-modality-raw-code`.
"""
* extension 0..0
* url 1..1
* value[x] 1..1 MS
* value[x] only CodeableConcept
* valueCodeableConcept from NexusEmrAppointmentModalityVS (extensible)
* valueCodeableConcept ^short = "Modality: normalized Nexus coding; source/raw coding MAY accompany it"


ValueSet: NexusEmrAppointmentModalityVS
Id: nexus-emr-appointment-modality-vs
Title: "Appointment Modality Value Set"
Description: "Delivery channel of an appointment. Extensible -- a pan-Canadian / Ontario standard code may be added as a parallel coding when the provincial IG defines one."
* ^status = #draft
* ^experimental = true
* ^url = "../ValueSet/nexus-emr-appointment-modality-vs"
* include codes from system NexusEmrAppointmentModalityCS

CodeSystem: NexusEmrAppointmentModalityCS
Id: nexus-emr-appointment-modality-cs
Title: "Appointment Modality Code System"
Description: "Normalized appointment/encounter delivery-channel codes. Encounter.class mapping: in-person -> #AMB; video | telephone | secure-message -> #VR (v3-ActCode)."
* ^url = "../CodeSystem/nexus-emr-appointment-modality-cs"
* ^status = #draft
* ^experimental = true
* ^caseSensitive = true
* ^content = #complete
* #in-person      "In person"       "Patient and provider are physically co-located."
* #video          "Video visit"     "Real-time audio-video visit (Ontario Health Virtual Visits: video)."
* #telephone      "Telephone visit" "Real-time audio-only (telephone) visit."
* #secure-message "Secure message"  "Asynchronous secure messaging (Ontario Health Virtual Visits: secure messaging)."
* #other          "Other"           "Modality not otherwise specified."