← Back to FairShift

📖 FairShift DSL Syntax Guide

Complete reference for defining schedules in plain English

How to use the DSL: Mix and match policies, employees, and rules in any order. Each line is parsed independently. Lines starting with # are comments.

📋 1. Select Policies

Use pre-built policy bundles by typing "Use policy:" followed by the exact policy name.

Syntax:

Use policy: [Exact Policy Name]

Examples:

Use policy: Basic Labor Laws ← Applies basic labor regulations
Use policy: Healthcare Basic ← Nurse-to-patient ratios, shift limits
Use policy: Trucking Hours of Service (HOS) ← Federal HOS rules

Available Policies:

👥 2. Add Employees

Define additional employees beyond the demo dataset. ⚠️ Role is REQUIRED!

Syntax:

Employee [Full Name], role: [Role] Employee [Full Name], role: [Role], seniority: [N] years Add employee [Full Name] as [Role] with [N] years experience [Full Name] as [Role]

✅ Valid Examples:

Employee Martin Gagne, role: Nurse
Employee Sarah Johnson, role: Nurse, seniority: 3 years
Add employee Mike Chen as Doctor with 8 years experience
Alice Williams as Driver
Bob Smith, Driver, certifications: CDL Class A

❌ WILL FAIL:

Employee Martin Gagne ← Missing role!
Martin Gagne, 3 years ← Missing role!

Optional Attributes:

⚠️ IMPORTANT: Skills Matching

Employees are matched to shifts based on their skills, not their role name. If a shift requires skills like "RN" or "CPR", employees must have those skills explicitly listed.

Example:

Employee Jane Doe, role: Nurse, skills: RN, CPR, First Aid

Without skills, the employee will be rejected from all shifts that require specific skills. Check the Employee Summaries and Shift-by-Shift Decision Trail after running the schedule to see why employees were selected or rejected.

📏 3. Add Custom Rules

Define constraints in plain English. Hard rules MUST be met. Soft rules are preferences (0-100 priority).

Hard Rules (Must be satisfied):

Hard: [rule description]

Supported Patterns:

Time & Rest:
Hard: At least 11 hours rest between shifts.
Hard: No employee works more than 6 consecutive days.
Hard: After a night shift, at least 12 hours before next shift.
Daily & Weekly Limits:
Hard: No employee works more than 60 hours per week.
Hard: No employee works more than 12 hours per day.
Hard: At least 2 days off every 14 days.
Hard: No more than 2 weekends in any 30-day window.
Trucking (HOS):
Hard: Maximum 11 hours of driving per day.
Hard: Maximum 14 hours on-duty per day.
Hard: At least 10 hours rest after 11 hours of driving.
Hard: Maximum 60 hours of driving per 7-day period.
Healthcare:
Hard: No more than 2 on-call shifts per 7 days.
Hard: Maximum patient ratio of 6:1 (patients per nurse).

Soft Rules (Preferences):

Soft (priority N): [rule description] Where N is 0-100: 80-100 = Very important 50-79 = Important 20-49 = Nice to have 0-19 = Low priority
Soft (priority 80): Balance weekend shifts evenly across the team.
Soft (priority 50): Minimize split shifts on the same day.
Soft (priority 70): Senior employees get first choice on weekends.

💡 Important: Only the patterns shown above are supported. Custom rules that don't match these patterns will be rejected during validation.

✅ Complete Example

# Select policies Use policy: Basic Labor Laws Use policy: Healthcare Basic # Add employees with roles Employee Martin Gagne, role: Nurse, seniority: 5 years Employee Sarah Johnson, role: Doctor, seniority: 8 years Bob Smith as Technician # Add custom rules Hard: No employee works more than 6 consecutive days. Hard: At least 11 hours rest between shifts. Soft (priority 80): Balance weekend shifts evenly across the team. Soft (priority 60): Senior employees get first choice on weekends.

⚠️ Common Mistakes

❌ Wrong ✅ Correct
Employee Martin Employee Martin Gagne, role: Nurse
Policy: Healthcare Use policy: Healthcare Basic
Soft: Balance weekends Soft (priority 70): Balance weekend shifts evenly.
Hard: Max 3 hours Hard: No employee works more than 3 hours per day.
← Back to FairShift