API Documentation

Beyond daily and weekly hour limits, you may need to control individual shift durations and guarantee weekly rest periods. These constraints prevent micro-shifts, enforce labor agreements, and ensure adequate recovery time.

Three new contract constraints

Each employee contract can specify:

All three are optional. If omitted, the solver doesn't enforce these constraints even if you set the corresponding weights.

Minimum shift duration

Prevent shifts that are too short to be worthwhile:

{
  "contract": {
    "minHoursPerShiftExcludingBreak": 3
  },
  "settings": {
    "minMinutesPerShift": {
      "firstPriorityWeight": 10,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    }
  }
}

With this configuration, the solver avoids creating shifts shorter than 3 hours. This prevents:

• Inefficient 1-2 hour shifts
• Excessive commuting relative to work time
• Fragmented schedules that hurt employee satisfaction

Use cases

• Healthcare: Minimum 4-hour shifts for nursing staff to handle proper handoffs
• Retail: Minimum 3-hour shifts to justify commute and setup time
• Call centers: Minimum 4-hour shifts for queue management consistency

Maximum shift duration

Cap how long a shift can be:

{
  "contract": {
    "maxHoursPerShiftExcludingBreak": 9
  },
  "settings": {
    "maxMinutesPerShift": {
      "firstPriorityWeight": 15,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    }
  }
}

This enforces shift length limits from labor agreements or safety regulations. Common uses:

• Manufacturing: 8-hour maximum per labor agreement
• Healthcare: 12-hour maximum to prevent fatigue-related errors
• Transportation: Regulatory limits on continuous driving

Note: This is excluding breaks. A 9-hour maximum allows for a 9-hour work period plus any mandated break time.

Minimum weekly rest

Guarantee a continuous rest period each week:

{
  "contract": {
    "minWeeklyRestHours": 36
  },
  "settings": {
    "minWeeklyRestMinutes": {
      "firstPriorityWeight": 20,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    }
  }
}

This enforces EU-style weekly rest requirements or other regulations mandating sustained time off. The solver ensures each employee gets at least 36 consecutive hours off per week.

Why this matters

Weekly rest differs from "days off" in important ways:

• Days off can be scattered (Monday off, Wednesday off, Friday off)
• Weekly rest must be continuous (Saturday noon through Monday noon)

Continuous rest provides actual recovery. Use high priority weights to make this a hard constraint.

Complete example

A hospital with comprehensive duration and rest rules:

{
  "employees": [
    {
      "id": 1,
      "name": "Dr. Martinez",
      "contract": {
        "hoursBetweenShift": 11,
        "maxHoursDay": 12,
        "maxHoursWeek": 48,
        "maxHoursMonth": 160,
        "maxWorkDaysMonth": 20,
        "maxConsecutiveDays": 5,
        "minConsecutiveDays": 2,
        "weekendWorkFrequency": 4,
        "maxNhours": 148,
        "minNhours": 120,
        "inKWeeks": 4,
        "maxConsecutiveLateShifts": 3,
        "maxConsecutiveNightShifts": 3,
        "shiftTimeOfDayRotationPattern": "E-L-N",
        "minHoursPerShiftExcludingBreak": 4,
        "maxHoursPerShiftExcludingBreak": 12,
        "minWeeklyRestHours": 36
      }
    }
  ],
  "settings": {
    "minMinutesPerShift": {
      "firstPriorityWeight": 8,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    },
    "maxMinutesPerShift": {
      "firstPriorityWeight": 15,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    },
    "minWeeklyRestMinutes": {
      "firstPriorityWeight": 20,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    }
  }
}

This contract ensures:

• No shift shorter than 4 hours (avoids inefficient micro-shifts)
• No shift longer than 12 hours (safety and labor compliance)
• Guaranteed 36-hour continuous weekly rest (EU compliance)

Implementation notes

Decimal values

All duration fields accept decimals:

{
  "minHoursPerShiftExcludingBreak": 3.5,
  "maxHoursPerShiftExcludingBreak": 8.75
}

The solver converts these to minutes internally, so 3.5 hours becomes 210 minutes.

Hard vs. soft constraints

Control enforcement through priority weights:

{
  "minWeeklyRestMinutes": {
    "firstPriorityWeight": 20  // Hard constraint - must satisfy
  }
}

vs.

{
  "minWeeklyRestMinutes": {
    "thirdPriorityWeight": 5  // Soft constraint - prefer but allow violations
  }
}

Use high first-priority weights for legal requirements. Use lower weights for preferences.

Backward compatibility

All three fields are optional. Existing contracts without these fields continue working unchanged:

{
  "contract": {
    "hoursBetweenShift": 11,
    "maxHoursDay": 12
    // No duration/rest fields - solver ignores those constraints
  }
}

You can add these constraints incrementally without breaking existing integrations.

Interaction with other constraints

These constraints work alongside existing ones:

• minHoursPerShiftExcludingBreak doesn't override maxHoursDay-both apply
• maxHoursPerShiftExcludingBreak can be stricter than maxHoursDay
• minWeeklyRestHours works with hoursBetweenShift (both enforce rest, different scopes)

The solver satisfies all active constraints based on their priority weights.

Common patterns

Shift-length "corridor"

{
  "minHoursPerShiftExcludingBreak": 6,
  "maxHoursPerShiftExcludingBreak": 9
}

Creates 6-9 hour shifts, avoiding both micro-shifts and excessive marathons.

EU compliance package

{
  "hoursBetweenShift": 11,
  "maxHoursWeek": 48,
  "minWeeklyRestHours": 24,
  "maxHoursPerShiftExcludingBreak": 13
}

Covers multiple EU Working Time Directive requirements.

Part-time flexibility

{
  "minHoursPerShiftExcludingBreak": 2,
  "maxHoursPerShiftExcludingBreak": 6
}

Allows shorter shifts for students or part-time staff while preventing single-hour assignments.