Shift type diversity

Employees have an expectation that the terms of their contracts are honored in the shifts they are assigned to work.

Employee contracts stipulate the conditions under which the employees work, including:

How many shift types they work in a given period.
How many types of tasks they can be assigned in a specific period.

For any employee shift scheduling solution to be feasible, it must take into account the contractual obligations between the employer and the employee.

This guide explains how to manage employee contract period rules with the following examples:

Shift types
Use tag types with period rules

To learn how to define a contract, see Employee contracts.

Prerequisites

To run the examples in this guide, you need to authenticate with a valid API key for the Employee Shift Scheduling model:

Log in to Timefold Platform: app.timefold.ai
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
Create a new API key or use an existing one. Ensure the list of models for the API key contains the Employee Shift Scheduling model.

In the examples, replace <API_KEY> with the API Key you just copied.

Counting days in period rules

By default, period rules count shifts within the defined period if the shift starts within the defined period. If you define a rule that an employee can only work 1 shift a day, a night shift that started on the previous day but ends the following morning will not be counted and another shift might be assigned.

To change this behavior change the field periodShiftOverlapKind from START_ONLY to START_AND_END.

{
  "periodRules": [
    {
      "id": "Max8HoursPerDayFullTime",
      "period": "DAY",
      "minutesWorkedMax": 480,
      "satisfiability": "REQUIRED",
      "periodShiftOverlapKind": "START_AND_END"
    }
}

1. Contractual hours:

2. Shift types

Period rules can define how many different types of shifts employees work in a given period. For instance, for shifts at different times of day, in different departments, or different job functions.

Shifts must be tagged with this additional information:

{
  "shifts": [
    {
      "id": "Mon AM",
      "start": "2027-02-01T06:00:00Z",
      "end": "2027-02-01T14:00:00Z",
      "tags": ["Early"]
    }
  ]
}

Period rules to define the maximum number of shift types worked per period are defined in contracts:

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "periodRules": [
        {
          "id": "Max2ShiftTypesPerWeek",
          "period": "WEEK",
          "satisfiability": "REQUIRED",
          "shiftTypesTagCategories": ["Early", "Afternoon", "Night"],
          "shiftTypesWorkedMax": 2
        }
      ]
    }
  ]
}

PeriodRules must include an ID.

period sets the period the rule applies to, for instance, DAY, WEEK, MONTH, SCHEDULE.

Further information about period:

DAY spans a single day and occurs every day in the schedule.

WEEK spans 7 days and occurs every week (including partial weeks) in the schedule. The default start of the week is Monday, but this can be overridden to any day in the week:

{
  "scheduleParameterization": {
    "weekStart": "THURSDAY"
  }
}

MONTH spans the entire month. MONTH has a variable number of days depending on the days in the month and occurs every month (including partial months) in the schedule.

SCHEDULE spans the entire schedule.

You can define custom periods to apply to this rule in the following way:

{
  "scheduleParameterization": {
    "periods": [
      {
        "id": "PAY_PERIOD",
        "dateSpans": [
          {
            "start": "2023-01-01",
            "end": "2023-01-15"
          }
        ]
      }
    ]
  }
}

The start and end dates are inclusive.

shiftTypesWorkedMax sets the maximum number of shift types the employee can work in the specified period.

shiftTypesTagCategories specifies which tags the rule applies to. Shifts can only be tagged with one of the tags specified by shiftTypesTagCategories.

The satisfiability of the rule can be REQUIRED or PREFERRED. REQUIRED is the default if omitted.

2.1. Required satisfiability

When the satisfiability of the rule is REQUIRED, the Shift types worked per period not in required range for employee hard constraint is invoked, which makes sure the number of shift types worked does not exceed the limit specified in shiftTypesWorkedMax.

Shifts will be left unassigned if assigning them would break the Shift types worked per period not in required range for employee constraint.

2.2. Preferred satisfiability

When the satisfiability of the rule is PREFERRED, the Shift types worked per period not in preferred range for employee soft constraint is invoked.

With a satisfiability of PREFERRED a shiftTypesWorkedMin value can also be provided to set the preferred minimum number of shifts worked.

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "periodRules": [
        {
          "id": "Max2ShiftTypesPerWeek",
          "period": "WEEK",
          "satisfiability": "PREFERRED",
          "shiftTypesTagCategories": ["Early", "Afternoon", "Night"],
          "shiftTypesWorkedMIN": 2,
          "shiftTypesWorkedMax": 3
        }
      ]
    }
  ]
}

This constraint adds a soft penalty to the run score when the number of assigned shift types is below the limit defined by shiftTypesWorkedMin or above the limit defined by shiftTypesWorkedMax, incentivizing Timefold to find an alternative solution.

2.3. Shift Types worked rules example

In the following example, Ann and Beth have a contract that limits their hours to 8 per day and two different shift types in a week. There are 11 shifts over 5 days with three different shift types. Ann and Beth are only assigned to 2 different shift types each. 2 shifts are left unassigned.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Contract period rules shift types example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Max8HoursPerDay",
            "period": "DAY",
            "satisfiability": "REQUIRED",
            "minutesWorkedMax": 480
          },
          {
            "id": "Max2ShiftTypesPerWeek",
            "period": "WEEK",
            "satisfiability": "REQUIRED",
            "shiftTypesTagCategories": ["Early", "Afternoon", "Night"],
            "shiftTypesWorkedMax": 2
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      },
      {
        "id": "Beth",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon AM",
        "start": "2027-02-01T06:00:00Z",
        "end": "2027-02-01T14:00:00Z",
        "tags": ["Early"]
      },
      {
        "id": "Mon PM",
        "start": "2027-02-01T14:00:00Z",
        "end": "2027-02-01T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Tue AM",
        "start": "2027-02-02T06:00:00Z",
        "end": "2027-02-02T14:00:00Z",
        "tags": ["Early"]
      },
      {
        "id": "Tue PM",
        "start": "2027-02-02T14:00:00Z",
        "end": "2027-02-02T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Tue Night",
        "start": "2027-02-02T22:00:00Z",
        "end": "2027-02-03T06:00:00Z",
        "tags": ["Night"]
      },
      {
        "id": "Wed PM",
        "start": "2027-02-03T14:00:00Z",
        "end": "2027-02-03T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Wed Night",
        "start": "2027-02-03T22:00:00Z",
        "end": "2027-02-04T06:00:00Z",
        "tags": ["Night"]
      },
      {
        "id": "Thu AM",
        "start": "2027-02-04T06:00:00Z",
        "end": "2027-02-04T14:00:00Z",
        "tags": ["Early"]
      },
      {
        "id": "Thu PM",
        "start": "2027-02-04T14:00:00Z",
        "end": "2027-02-04T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Thu Night",
        "start": "2027-02-04T22:00:00Z",
        "end": "2027-02-05T06:00:00Z",
        "tags": ["Night"]
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Contract period rules shift types example",
    "submitDateTime": "2025-04-01T06:22:34.128322433Z",
    "startDateTime": "2025-04-01T06:22:47.854671277Z",
    "activeDateTime": "2025-04-01T06:22:48.101053008Z",
    "completeDateTime": "2025-04-01T06:27:49.015637737Z",
    "shutdownDateTime": "2025-04-01T06:27:49.319329116Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-2medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon AM",
        "employee": "Ann"
      },
      {
        "id": "Mon PM",
        "employee": "Beth"
      },
      {
        "id": "Tue AM",
        "employee": "Ann"
      },
      {
        "id": "Tue PM",
        "employee": "Beth"
      },
      {
        "id": "Tue Night",
        "employee": null
      },
      {
        "id": "Wed PM",
        "employee": "Ann"
      },
      {
        "id": "Wed Night",
        "employee": "Beth"
      },
      {
        "id": "Thu AM",
        "employee": "Ann"
      },
      {
        "id": "Thu PM",
        "employee": "Beth"
      },
      {
        "id": "Thu Night",
        "employee": null
      }
    ]
  },
  "inputMetrics": {
    "employees": 2,
    "shifts": 10,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 8,
    "unassignedShifts": 2,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 2,
    "assignedMandatoryShifts": 8,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann and Beth assigned to only 2 shifts types.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 8,
  "unassignedShifts": 2,
  "activatedEmployees": 2,
  "assignedMandatoryShifts": 8
}

3. Use tag types with period rules

Tags and TagTypes can be used to assign shifts to employees.

Tags can be grouped into tag types, for example, tag types could be department, employment type, or specific task types.

PeriodRules can include tag types, effectively filtering out all other tags and tag types.

In the following example, the tags Task A and Task B are of tag type Task.

{
  "tagTypes": [
    {
        "id": "Task"
    }
  ],
  "tags": [
    {
        "id": "Task A",
        "tagType": "Task"
    },
    {
        "id": "Task B",
        "tagType": "Task"
    }
  ]
}

By grouping tags into a tag type, employees can be assigned shifts that belong to a tag type without specifying each tag for the employee.

PeriodRules can include uniqueTagsLimit to limit the number of tags that can be used to assign individual employees to shifts. This is useful when employees can be assigned shifts that focus on a range of different tasks, but it’s counterproductive to have them switching to different types of tasks each day, you can limit the different number of tasks they are assigned across a period. This could include shifts that involve operating different kinds of machinery, being assigned to specific lines in a call center, or driving predefined routes as a driver.

{
  "id": "periodRuleContract",
  "periodRules": [
    {
      "id": "max2TasksRule",
      "period": "WEEK",
      "satisfiability": "REQUIRED",
      "uniqueTagsLimit": {
        "tagsMax": 2,
        "includeTagTypes": ["Tasks"]
      }
    }
  ]
}

PeriodRules must include an ID.

period sets the period the rule applies to, for instance, DAY, WEEK, MONTH, SCHEDULE.

Further information about period:

DAY spans a single day and occurs every day in the schedule.

WEEK spans 7 days and occurs every week (including partial weeks) in the schedule. The default start of the week is Monday, but this can be overridden to any day in the week:

{
  "scheduleParameterization": {
    "weekStart": "THURSDAY"
  }
}

MONTH spans the entire month. MONTH has a variable number of days depending on the days in the month and occurs every month (including partial months) in the schedule.

SCHEDULE spans the entire schedule.

You can define custom periods to apply to this rule in the following way:

{
  "scheduleParameterization": {
    "periods": [
      {
        "id": "PAY_PERIOD",
        "dateSpans": [
          {
            "start": "2023-01-01",
            "end": "2023-01-15"
          }
        ]
      }
    ]
  }
}

The start and end dates are inclusive.

uniqueTagsLimit must include tagsMax and includeTagTypes.

tagsMax specifies the maximum number of tags that can be used to assign individual employees to shifts.

includeTagTypes specific which tagType to include in the rule.

The satisfiability of the rule can be REQUIRED or PREFERRED. REQUIRED is the default if omitted.

3.1. Required satisfiability

When the satisfiability of the rule is REQUIRED, the Unique tags per period not in required range for employee hard constraint is invoked, which makes sure the number of tags used to assign shifts to individual employees does not exceed the limit specified in tagsMax.

Shifts will be left unassigned if assigning them would break the Unique tags per period not in required range for employee constraint.

3.2. Preferred satisfiability

When the satisfiability of the rule is PREFERRED, the Unique tags per period not in preferred range for employee soft constraint is invoked.

{
  "id": "periodRuleContract",
  "periodRules": [
    {
      "id": "max2TasksRule",
      "period": "WEEK",
      "satisfiability": "PREFERRED",
      "uniqueTagsLimit": {
        "tagsMax": 2,
        "includeTagTypes": ["Task"]
      }
    }
  ]
}

This constraint adds a soft penalty to the run score when the number of tags used to assign shifts to an individual employee exceeds the limit set in tagsMax, incentivizing Timefold to find an alternative solution.

3.3. Unique tags example

In the following example, there are 5 shifts which are tagged for 3 different tasks. The tagsMax limit is set to 2, so shifts with 1 of the tasks are left unassigned.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Contract period unique tags example"
    }
  },
  "modelInput": {
    "tagTypes": [
      {
        "id": "Tasks"
      }
    ],
    "tags": [
      {
        "id": "Task A",
        "tagType": "Tasks"
      },
      {
        "id": "Task B",
        "tagType": "Tasks"
      },
      {
        "id": "Task C",
        "tagType": "Task"
      }
    ],
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Max2TasksRule",
            "period": "WEEK",
            "uniqueTagsLimit": {
              "tagsMax": 2,
              "includeTagTypes": [
                "Tasks"
              ]
            }
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon AM",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "tags": ["Task A"]
      },
      {
        "id": "Tue",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z",
        "tags": ["Task B"]
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17:00:00Z",
        "tags": ["Task C"]
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:00:00Z",
        "end": "2027-02-04T17:00:00Z",
        "tags": ["Task A"]
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z",
        "tags": ["Task B"]
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Contract period unique tags example",
    "submitDateTime": "2025-04-02T05:01:50.72460623Z",
    "startDateTime": "2025-04-02T05:02:01.381568012Z",
    "activeDateTime": "2025-04-02T05:02:01.511395777Z",
    "completeDateTime": "2025-04-02T05:07:02.332743181Z",
    "shutdownDateTime": "2025-04-02T05:07:02.478167535Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-1medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon AM",
        "employee": "Ann"
      },
      {
        "id": "Tue",
        "employee": "Ann"
      },
      {
        "id": "Wed",
        "employee": null
      },
      {
        "id": "Thu",
        "employee": "Ann"
      },
      {
        "id": "Fri",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 1,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 4,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to shifts with 2 tasks. Shifts with 1 task are left unassigned.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 4,
  "unassignedShifts": 1,
  "activatedEmployees": 1,
  "assignedMandatoryShifts": 4
}

See the full API spec or try the online API.
Learn more about employee shift scheduling from our YouTube playlist.
Working with Employee availability.

Shift type diversity

Prerequisites

Counting days in period rules

1. Contractual hours:

2. Shift types

2.1. Required satisfiability

2.2. Preferred satisfiability

2.3. Shift Types worked rules example

3. Use tag types with period rules

3.1. Required satisfiability

3.2. Preferred satisfiability

3.3. Unique tags example

Next