hughbris
commented
6 years ago OK, thoughts developing ..
Calendars are sets of times for a service (but not periods of time). Example is opening in data.sample.yaml. Child of plugin top-level hours element with a 1-many relationship.
Timetables are specific sets of time in calendars representing regular day schedules, exception day schedules, and irregular period schedules. They are direct children of calendars and must use the names regular, exceptions, and periods. Only regular is required of the three.
regular timetables have child properties labeled for days of the week, which contain schedules. Missing days of the week are assumed closed, though templates may treat them differently if they are completely omitted.
exceptions timetables have child properties labeled for dates in "yyyy-mm-dd" format. These dates have child properties hours containing a schedule, and optionally a comment property, which can be used to render a reason for the exception.
periods timetables describe periods of time (e.g. vacation hours) with irregular service hours. They contain the properties start (required), finish (required), description for a summary of the availability (e.g. "Closed"), name for the name/reason for the irregularity, and then regular (required, Regular timetable structure) and exceptions (optional, Exception timetable structure).
Exceptions and Periods are collectively known as irregular timetables (sometimes useful in rendering).
Schedules are service availability times for a day or Period. They can be children of hours.<calendar>.regular.<dayname>, hours.<calendar>.exceptions.<date>.hours, or hours.<calendar>.periods[<seq>].<regular.<dayname>|exceptions.<date>.hours>. They contain zero or more windows.
Windows are the opening periods within a day schedule. They must consist of one opens and one shuts property and the former should be before the latter obviously (or I don't know what will happen!).
This plugin doesn't use consistent terms, as it's been built up on and off over a couple of years. It's going to quickly get confusing if I don't standardise and define a few names. They should be used in docs, front end templates, and code alike.
In particular: