SchedAI Input Specs
SchedAI Employee Input Specs
SchedAI Employee uses employees.csv and shifts.csv as the required scheduling inputs, with preferences.csv as an optional penalty layer.
Overview
Use this guide to prepare valid input files for this workspace. Review the required files, exact column names, example rows, and common formatting rules before uploading.
Required files
2
Optional files
1
Spec sections
1
Upload section
Employee Upload Bundle
Upload roster, shift demand, and any optional preference costs using the workforce CSV format accepted by the workspace.
Required file
employees.csv
Employee roster input.
Requirements
Required columns
employee_idskillsmax_shiftsavailability
Optional columns
max_hours_per_daymax_hours_per_weekmin_hours_per_weekmin_rest_minutes
Row identity
- Required row identity: employee_id.
- employee_id values must stay unique.
Rejected wrong-file signatures
- Reject uploads that match this wrong-file signature: shift_id + start + end.
- Reject uploads that match this wrong-file signature: employee_id + shift_id + cost.
Normalization notes
- Human times in availability are normalized to backend minute fields; you do not need to provide start_minute or end_minute columns.
Format limitations
- skills uses | or ; separators; availability uses semicolon-separated qualifier:start-end segments where the time portion accepts HH:MM and AM/PM values.
Unsupported currently
- Day-only overnight availability windows are blocked — provide an ISO date qualifier for any window that crosses midnight.
- Raw start_minute or end_minute columns are not needed in the upload; the app normalizes human times internally.
Value rules and examples
- skills accepts | or ; separators, for example security;triage or security|triage.
- availability uses qualifier:start-end segments separated with semicolons, for example mon:08:00-17:00; 2026-05-04:10:00 PM-6:00 AM.
- Qualifier may be a weekday (mon–sun), wildcard (*), or ISO date (YYYY-MM-DD).
- Times in availability accept HH:MM, AM/PM, bare hours, and half-hour values, for example 8, 08:00, 8:30, 8:30 AM, 10 PM.
- Because availability uses colons inside HH:MM values, the parser splits on the first colon after the qualifier — mon:08:00-17:00 is valid.
- Dated overnight availability is supported — use an ISO date qualifier, for example 2026-05-04:10:00 PM-6:00 AM.
- Day-only overnight availability (e.g. mon:22:00-06:00) is blocked; use an ISO date qualifier for any window that crosses midnight.
- max_shifts must be at least 1 for every employee.
Example CSV table
| employee_id | skills | max_shifts | availability | max_hours_per_day | max_hours_per_week | min_hours_per_week | min_rest_minutes |
|---|---|---|---|---|---|---|---|
| E1 | security;triage | 3 | 2026-05-04:10:00 PM-6:00 AM | 10 | 40 | 480 | |
| E2 | triage|front_desk | 3 | 2026-05-04:08:00-18:00 | 10 | 40 | 480 |
Required file
shifts.csv
Shift demand input.
Requirements
Required / alternative columns
shift_idday or datestartenddemandrequired_skills
Optional columns
Row identity
- Required row identity: shift_id.
- shift_id values must stay unique.
Approved aliases
- start: start_time
- end: end_time
Rejected wrong-file signatures
- Reject uploads that match this wrong-file signature: employee_id + skills + availability.
- Reject uploads that match this wrong-file signature: employee_id + shift_id + cost.
Normalization notes
- Human times in start/end are normalized to backend minute fields; you do not need to provide start_minute, end_minute, or ends_next_day columns.
Format limitations
- Use day for weekly schedules or date=YYYY-MM-DD for explicit calendar schedules; start/end accept HH:MM and AM/PM in addition to bare hours.
Unsupported currently
- W1-Mon / W2-Tue labels are not accepted.
- Day-only overnight shifts are blocked — provide an ISO date column for any shift where end is earlier than start.
Value rules and examples
- Use day labels such as mon or tue for weekly schedules, or date=YYYY-MM-DD for explicit calendar schedules.
- W1-Mon and W2-Tue labels are not accepted.
- start and end accept HH:MM, AM/PM, bare hours, and half-hour values, for example 8, 08:00, 8:30, 8:30 AM, 10 PM.
- Dated overnight shifts are supported — use an ISO date and crossing times, for example date=2026-05-04, start=10:00 PM, end=6:00 AM.
- Day-only overnight shifts (day label with end earlier than start) are blocked; use an ISO date for overnight shifts.
- required_skills accepts | or ; separators when a shift needs multiple skills.
Example CSV table
| shift_id | date | day | start | end | demand | required_skills | priority |
|---|---|---|---|---|---|---|---|
| S1 | 2026-05-04 | 8:30 AM | 4:45 PM | 1 | triage | 1 | |
| S2 | 2026-05-04 | 10:00 PM | 6:00 AM | 1 | security | 2 |
Optional file
preferences.csv
Optional employee-to-shift cost preferences.
Requirements
Required columns
employee_idshift_idcost
Optional columns
Rejected wrong-file signatures
- Reject uploads that match this wrong-file signature: shift_id + day + start + end.
- Reject uploads that match this wrong-file signature: employee_id + skills + availability.
Reference requirements
- employee_id must match employees.csv and shift_id must match shifts.csv.
Value rules and examples
- employee_id and shift_id must reference rows already present in employees.csv and shifts.csv.
- Use cost >= 0.
- Leave this file out when you do not need preference penalties.
Example CSV table
| employee_id | shift_id | cost |
|---|---|---|
| E1 | S2 | 0 |
| E2 | S1 | 0 |
Common mistakes
- Using shifts where end is earlier than start.
- Leaving max_shifts below 1.
- Referencing employees or shifts in preferences.csv that do not exist in the required files.
Quick rules
- employees.csv must include employee_id, skills, max_shifts, and availability.
- shifts.csv must include shift_id, day or date, start, end, demand, and required_skills.
- preferences.csv is optional, but when present it must include employee_id, shift_id, and cost.
- HH:MM, half-hour, and AM/PM times are accepted in start, end, and availability; dated overnight shifts and dated overnight availability windows are supported.
- Day-only overnight shifts and day-only overnight availability are blocked — use an ISO date for any window that crosses midnight.
Navigate
Keep the right guide close by
Pair this upload guide with the product page for workflow context or the resources hub for related public material.
Navigate
Keep the right input guide close
Return to the input-spec library for another upload contract, or go back to the resource hub for quickstarts, how-to guides, and use cases.