Skip to main content
Fairness buckets ensure equitable workload distribution among a specific group of employees for selected shifts during a defined period.

​
Use Cases

  • Equal shift distribution - Ensure all team members get similar hours
  • Weekend rotation - Fairly distribute unpopular shifts
  • Skill-based teams - Balance workload within specialized groups

​
Basic Fairness

Define a fairness bucket with employees, shifts, and the evaluation period:
The solver distributes the 6 shifts evenly: each employee gets 2 shifts during the week.

​
Fairness Properties

​
employees
array
required
List of employee names to include in this fairness group
​
shifts
array
required
List of shift names to distribute fairly among the employeesNote: the fairness target is currently calculated from the employee’s total assigned workload across the whole plan, not just the shifts listed here. For accurate results, make sure a given employee’s fairness-relevant shifts are the only shifts assigned to them during the bucket’s window, or that all of the employee’s shifts in the plan are included in this list.
​
period
object
Time period during which fairness is evaluatedCurrently accepted by the API but not yet enforced by the solver — fairness is always evaluated over the full set of assignments for the referenced employees. Do not rely on period to scope the evaluation window.
​
target
string (ISO 8601 duration)
required
Target workload per employee (e.g., PT40H for 40 hours)
Note: every name in employees and shifts must exactly match a name from the request’s top-level employees/shifts arrays. An unrecognized name causes the request to fail with an error such as cannot find employee name <name> in fairness bucket.

​
Multiple Fairness Buckets

Create separate fairness groups for different teams or shift types:
Each bucket’s target is tracked separately per employee group. However, the fairness constraint sums an employee’s total workload across all assignments in the plan, not just the shifts listed in that bucket. If, for example, Alice or Bob also picked up evening shifts elsewhere in the request, those hours would count toward the morning bucket’s target too — the buckets are only truly independent if each employee’s shifts in the plan are fully covered by a single bucket.

​
Target-Based Fairness

Set a specific workload target instead of equal distribution:
Use target when employees have different availability or contract types but should work toward the same weekly hours.

​
Fairness vs Rules

Fairness is a soft constraint with a default weight of 1soft. If it’s competing with other objectives (e.g. wage or priority) and not being honored strongly enough, increase its weight in the request, e.g. "weights": { "fairness": "10soft" }.