Concretely, a _Slot Publisher_ hosts four kinds of files:
* **Bulk Publication Manifest**. The manifest is a JSON file serving as the entry point for slot discovery. It provides links that clients can follow to retrieve all the other files. The manifest is always hosted at a URL that ends with `$bulk-publish` (a convention used when publishing data sets using FHIR; this convention applies any time a potentially large data set needs to be statically published).
* [Details on JSON structure](#manifest-file)
* [Example file](https://raw.githubusercontent.com/smart-on-fhir/smart-scheduling-links/master/examples/$bulk-publish) showing a manifest for the fictional "SMART Vaccine Clinic", a regional chain with ten locations in Massachusetts.
* **Location Files**. Each line contains a minified JSON object representing a physical location where appointments are available.
* [Details on JSON structure](#location-file)
* [Example file](https://raw.githubusercontent.com/smart-on-fhir/smart-scheduling-links/master/examples/locations.ndjson) showing ten locations for the fictional "SMART Vaccine Clinic". Each line provides details about a single physical location in the MA area.
* **Schedule Files**. Each line contains a minified JSON object representing the calendar for a healthcare service offered at a specific location.
* [Details on JSON structure](#schedule-file)
* [Example file](https://raw.githubusercontent.com/smart-on-fhir/smart-scheduling-links/master/examples/schedules.ndjson) showing ten locations for the fictional "SMART Vaccine Clinic". Since SMART Vaccine Clinics are offer only COVID-19 services, there is a single Schedule (the COVID-19 vaccination schedule) for each location. Each line provides details about a single schedule.
* **Slot Files**. Each line contains a minified JSON object representing an appointment slot (busy or free) for a healthcare service at a specific location.
* [Details on JSON structure](#slot-file)
* [Example file](https://raw.githubusercontent.com/smart-on-fhir/smart-scheduling-links/master/examples/slots-2021-W09.ndjson) showing coarse-grained slots for a single week, across all ten "SMART Vaccine Clinic" sites. (_Note: The choice to break down slots into weekly files is arbitrary; the fictional Clinic could instead choose to host a single slot file, or produce location-specific files, or even group slots randomly._) Each of the published slots in this example includes a "capacity" extension indicating that the slot has a capacity of 100 patients; furthermore the slots include only coarse-grained timing (indicating they fall sometime beetween 9a and 6p ET, the clinic's fictional hours of operation). Ideally, Slot Publishers should provide finer-grained slot information with specific timing (see "progressive enhancement" in [Goals](#goals-for-slot-discovery) above), but coarse-grained slots provide an easy way to get started.
A client queries the manifest on a regular basis, e.g. once every 1-5 minutes. The client iterates through the links in the manifest file to retrieve any Location, Schedule, or Slot files it is interested in. (Clients SHOULD ignore any output items with types other than Location, Schedule, or Slot.)
### Timestamps
Wherever “timestamps” are used in this specification, they SHALL be in the format `YYYY-MM-DDThh:mm:ss.sss+zz:zz` (e.g. `2015-02-07T13:28:17.239+02:00` or `2017-01-01T00:00:00Z`). The time SHALL specified at least to the second and SHALL include a time zone offset (for UTC, the offset MAY be `Z`). These timestamps match [FHIR’s “instant” format][fhir-instant], and are also valid ISO 8601 timestamps.
### `Accept` Headers
For Bulk Publication Manifest requests, servers SHALL support at least the following `Accept` headers from a client, returning the same FHIR JSON payload in all cases:
1. No `Accept` header present
1. `Accept: application/json`
For Bulk Output File requests, servers SHALL support at least the following `Accept` headers from a client, returning the same FHIR NDJSON payload in all cases:
1. No `Accept` header present
1. `Accept: application/fhir+ndjson`
### Performance Considerations
* _Slot Publishers_ SHOULD annotate each output with a list of states or jurisdictions as a hint to clients, allowing clients to focus on fetching data for the specific states or geographical regions where they operate; this is helpful for clients with limited regions of interest.
* _Slot Publishers_ SHOULD include a [`Cache-Control: max-age=| field name | type | description |
|---|---|---|
resourceType | string | fixed value of "Schedule" |
id | string | a unique identifier for this schedule (up to 64 alphanumeric characters and may include - and .) |
actor | array with one JSON object | |
→ reference | string | the location where appointments are available formed as Location + / + the id value of an entry in a Location File (e.g., "Location/123") |
serviceType | array of JSON objects | Each object is a standardized concept indicating what services are offered. For COVID-19 immunization Schedules, two standardized codings must be included:
[{
"system": "http://terminology.hl7.org/CodeSystem/service-type",
"code": "57",
"display": "Immunization"
}, {
"system": "http://fhir-registry.smarthealthit.org/CodeSystem/service-type",
"code": "covid19-immunization"
"display": "COVID-19 Immunization Appointment"
}]
Additional serviceTypes may be included if this schedule offers services beyond COVID-19 immunizations; or additional codings may be included to convey more nuanced information about the COVID-19 immunizations offered. The example resource below shows a serviceType that can be used verbatim to advertise a COVID-19 immunization schedule. (Why two Codings? One expresses the fact that the slot is for an immunization service, and the other is specific to COVID-19. This structure follows a convention in FHIR for expressing "codeable concepts" -- see here for details.) |
extension | array of JSON objects | see details below |