Need-to-Know
Districts provide calendar and schedule information as structured CSV files. You will need up to four files depending on your setup:
school_calendars.csv— Defines each school calendarschedules.csv— Defines the daily schedule types used throughout the yearperiods.csv— Defines the periods within each scheduledays.csv— Maps each calendar date to the schedule in use that day
These files only need to be uploaded at setup or when calendar/schedule changes occur.
File 1: School Calendars
Filename: school_calendars.csv
One row per school calendar. This file identifies each calendar and connects it to the correct school in your OneRoster data.
Column | Description |
| Unique identifier for the calendar |
| Must match the OneRoster school/org identifier |
| School year (e.g., 2024–2025) |
File 2: Schedules
Filename: schedules.csv
Defines the daily schedule types used by the school or district throughout the year (e.g., regular days, early release days, A/B block schedules).
Column | Description |
| Unique identifier for the schedule |
| Optional but helpful label (e.g., "Regular Day", "Early Release") |
| Space-separated grade levels that use this schedule (e.g., "9 10 11 12") |
File 3: Periods
Filename: periods.csv
Defines the individual periods or blocks within each schedule. Each period links back to its parent schedule.
Column | Description |
| Unique identifier for the period |
| Must match the |
| Name of the period or block (e.g., "Period 1", "Advisory") |
| Numeric identifier for the period |
| Start time in HH:MM (24-hour format) |
| End time in HH:MM (24-hour format) |
File 4: Days
Filename: days.csv
Maps each calendar date to the schedule in use that day. If a school uses multiple schedules on the same date—for example, different bell schedules for different grade bands—include one row per schedule.
Column | Description |
| Must match the |
| Date in YYYY-MM-DD format |
| Cycle day label if applicable (e.g., A, B) |
| Must match the |
Tips & Troubleshooting
✔ My school uses A/B or block scheduling Use the cycle_day column in days.csv to distinguish between schedule types, and make sure each schedule variant has its own entry in schedules.csv with the correct periods defined in periods.csv.
✔ Different grade levels follow different bell schedules Include one row per schedule in days.csv for any date where multiple schedules apply, and use the grades column in schedules.csv to specify which grade levels each schedule applies to.
✔ Our calendar changes mid-year Re-upload days.csv (and any affected schedule files) whenever your calendar changes. You don't need to re-upload files that haven't changed.