Schedule Template Rule Extension¶
| Canonical | https://fhir.apps.health/StructureDefinition/nexus-schedule-template-rule |
|---|---|
| Status | draft · 1.33.0 |
| Base | Extension (constraint) |
| Context | Schedule (element) |
| Source | FSH · JSON |
One rule of a provider's schedule templates, carried on the Schedule: which template covers a
time range on the days the rule names. A schedule carries one extension per rule.
FSH
The authored source of truth: extensions/ScheduleTemplateRuleExtension.fsh (edit on GitHub). One FSH file may define several related artifacts.
// ScheduleTemplateRuleExtension.fsh
// The rules a provider's schedule templates follow -- which template covers which time range on
// which days -- carried on the `Schedule`, one extension per rule.
//
// WHY ON THE SCHEDULE AND NOT ON EACH SLOT. A template is a span of the day, and the span need not
// line up with the slot grid: one may run 14:20 to 16:05 on a 15-minute grid, or cover a time no
// slot exists for. Carried on each slot the span exists only where slots happen to be, and only at
// their resolution; carried here it is stated once, in its own terms, and every day the schedule
// covers is read from it. What a rule carries, and how rules are read together, is stated once in
// the Description below.
Invariant: nexus-schedule-template-rule-days-or-date
Description: "A rule names the weekdays it recurs on or the one date it applies on -- never both, never neither"
Severity: #error
Expression: "extension('daysOfWeek').exists() xor extension('date').exists()"
// `value.ofType(time)`, NOT `valueTime`, here and in `interval-needs-start` below (`ofType(positiveInt)`,
// `ofType(Period)`): Extension.value[x] is a choice, and an invariant whose expression fails to
// evaluate is not enforced at all.
Invariant: nexus-schedule-template-rule-end-after-start
Description: "A rule ends after it starts"
Severity: #error
Expression: "extension('end').value.ofType(time) > extension('start').value.ofType(time)"
Invariant: nexus-schedule-template-rule-effective-recurring-only
Description: "Only a recurring rule carries an effective period; a dated rule already names its one day"
Severity: #error
Expression: "extension('effective').exists() implies extension('daysOfWeek').exists()"
Invariant: nexus-schedule-template-rule-interval-needs-start
Description: "A rule that applies every second week or less often names in effective.start the date its weeks are counted from"
Severity: #error
Expression: "extension('weekInterval').exists() implies (extension('weekInterval').value.ofType(positiveInt) <= 1 or extension('effective').value.ofType(Period).start.exists())"
Extension: NexusScheduleTemplateRule
Id: nexus-schedule-template-rule
Title: "Schedule Template Rule Extension"
Description: """
One rule of a provider's schedule templates, carried on the `Schedule`: which template covers a
time range on the days the rule names. A schedule carries one extension per rule.
**Two kinds of rule.** A recurring rule names in `daysOfWeek` the weekdays it applies on, and may
name in `effective` the dates it applies between; with no `effective` it is open-ended. A dated
rule names its one day in `date`. A rule carries `daysOfWeek` or `date`, never both.
**A rule may apply on alternate weeks.** `weekInterval` says how many weeks apart a recurring rule
applies; how the weeks are counted is stated on that element.
**A dated rule describes its date in full.** When any dated rule exists for a date, the recurring
rules are not applied on that date: the dated rules alone say what covers it. This is how a
schedule assigns a whole day at once, and it keeps the reading a per-date entry has in the
scheduling systems these rules are drawn from, where one `scheduledate` row assigns the whole day.
**Rules on one day must not overlap in time.** A writer keeps them apart. A reader that meets
overlapping rules shows all of them rather than choosing between them, so the overlap is seen and
corrected instead of hidden. The range is half-open: a rule ending at 12:00 covers up to but not
including 12:00, so a rule starting at 12:00 on the same day does not overlap it.
**Times are clinic-local wall-clock times.** `start` and `end` are times of day in the clinic's
time zone, not instants, so a rule stays put across a daylight-saving change: 09:00 is 09:00 on
every day the rule applies. A reader placing a rule on a day resolves it in the clinic's time zone.
**The rules describe templates only. They are not availability.** Bookable time is still the
Schedule's Slots. Nothing about Slot, free/busy, `Slot.appointmentType` or `Schedule.actor` changes
with this extension. A slot does not carry its template: `Slot.serviceType` keeps its delivery-mode
and raw source codings and is not bound to the templates value set, and which template covers a
slot is read from these rules.
**A template's attributes still come from the value set.** The rule names a template by its coding;
its colour, booking limit and booking warning are read from that code's concept in the clinic's
stored `nexus-schedule-templates` value set and are never repeated on the rule.
"""
* ^url = $NexusScheduleTemplateRule
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Schedule"
* obeys nexus-schedule-template-rule-days-or-date and nexus-schedule-template-rule-end-after-start and nexus-schedule-template-rule-effective-recurring-only and nexus-schedule-template-rule-interval-needs-start
* . ^short = "One schedule-template rule: which template covers a time range on the days it names"
* url 1..1
* value[x] 0..0
* extension contains
daysOfWeek 0..* MS and
date 0..1 MS and
start 1..1 MS and
end 1..1 MS and
template 1..1 MS and
effective 0..1 MS and
weekInterval 0..1 MS
* extension[daysOfWeek] ^short = "The weekdays a recurring rule applies on"
* extension[daysOfWeek] ^definition = "The weekdays a recurring rule applies on, one code per day. Present on a recurring rule and absent from a dated one: a rule carries this or `date`, never both."
* extension[daysOfWeek].value[x] 1..1 MS
* extension[daysOfWeek].value[x] only code
* extension[daysOfWeek].value[x] from http://hl7.org/fhir/ValueSet/days-of-week (required)
* extension[date] ^short = "The one day a dated rule applies on"
* extension[date] ^definition = "The one day a dated rule applies on. A dated rule describes that date in full: when any dated rule exists for a date, no recurring rule is applied on it. A rule carries this or `daysOfWeek`, never both."
* extension[date].value[x] 1..1 MS
* extension[date].value[x] only date
* extension[start] ^short = "Clinic-local wall-clock time the rule begins"
* extension[start] ^definition = "The time of day the rule begins, in the clinic's time zone. A time of day and not an instant, so it holds across a daylight-saving change."
* extension[start].value[x] 1..1 MS
* extension[start].value[x] only time
* extension[end] ^short = "Clinic-local wall-clock time the rule ends; after start"
* extension[end] ^definition = "The time of day the rule ends, in the clinic's time zone, after `start`. Exclusive: a rule ending at 12:00 covers up to but not including 12:00, so a rule starting at 12:00 on the same day does not overlap it."
* extension[end].value[x] 1..1 MS
* extension[end].value[x] only time
* extension[template] ^short = "The template that covers the range, coded from the templates value set"
* extension[template] ^definition = "The template that covers the range, as one coding from the clinic's stored `nexus-schedule-templates` value set: a default from `nexus-schedule-template`, or one of the clinic's own under its own code system. The template's colour, booking limit and booking warning are read from that code's concept in the value set, not from the rule."
* extension[template].value[x] 1..1 MS
* extension[template].value[x] only Coding
* extension[template].value[x] from NexusScheduleTemplates (extensible)
* extension[effective] ^short = "The dates a recurring rule applies between; absent means open-ended"
* extension[effective] ^definition = "The dates a recurring rule applies between, both inclusive. Either bound may be absent: no `start` means the rule has always applied, no `end` means it applies until further notice, and no `effective` at all means both. Only a recurring rule carries it; a dated rule already names its one day. A rule with a `weekInterval` above 1 needs `start`."
* extension[effective].value[x] 1..1 MS
* extension[effective].value[x] only Period
* extension[weekInterval] ^short = "How many weeks apart a recurring rule applies; absent means every week"
* extension[weekInterval] ^definition = "How many weeks apart the rule applies: 2 is every other week, 3 every third; absent means every week. Weeks are counted from the week containing `effective.start`, weeks starting on Monday in the clinic's time zone, and the rule applies on a date whose week count from that week is a multiple of this value. A value above 1 needs `effective.start`, or there is no week to count from."
* extension[weekInterval].value[x] 1..1 MS
* extension[weekInterval].value[x] only positiveInt