Consecutive weekends off per period

There are different techniques for managing employee’s time off.

Consecutive weekends off per period can be specified per month or for the entire schedule.

This guide explains managing consecutive weekends off per period:

1. Define consecutive weekends off per period

Learn how to configure an API Key to run the examples in this guide:

  1. Log in to Timefold Platform: app.timefold.ai

  2. From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.

  3. 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.

Period rules are configured in contracts:

{
  "periodRules": [
    {
      "id": "min3ConsecutiveWeekendsOff",
      "period": "SCHEDULE",
      "consecutiveWeekendsOffLimit":
        {
          "consecutiveWeekendsOffMin": 3
        },
      "satisfiability": "REQUIRED"
    }
  ]
}

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.

The consecutiveWeekendsOffLimit object must include consecutiveWeekendsOffMin with the minimum number of consecutive weekends off. consecutiveWeekendsOffMin should be at least 2.

periodRules can include or exclude shifts based on shift tags.

{
  "periodRules": [
    {
      "id": "min3ConsecutiveWeekendsOff",
      "period": "SCHEDULE",
      "consecutiveWeekendsOffLimit":
        {
          "consecutiveWeekendsOffMin": 3
        },
      "satisfiability": "REQUIRED",
      "includeShiftTags": ["Part-time"],
      "shiftTagMatches": "ALL"
    }
  ]
}
Further information about including or excluding shifts with shift tags:

Shifts with specific tags can be included or excluded by the rule. Tags are defined in shifts:

{
  "shifts": [
    {
      "id": "2027-02-01",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "tags": ["Part-time"]
    }
  ]
}

Use includeShiftTags to include shifts with specific tags or excludeShiftTags to exclude shifts with specific tags.

shiftTagMatches can be set to ALL or ANY. The default behavior for shiftTagMatches is ALL, and if omitted, the default ALL will be used.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

{
  "includeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute must be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute must be present in the shift.

{
  "excludeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you want to exclude things in combination with each other. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to All, will exclude shifts that include the tags Part-time and Weekend from the rule. Shifts tagged only Part-time or only Weekend will not be excluded.

With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you need to exclude tags regardless of their relationship to other tags. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to ANY, will exclude any shift that includes the tags Part-time or Weekend, whether they occur together or not.

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

2. Required consecutive weekends off per period

When the satisfiability of the rule is REQUIRED, the Consecutive weekends off per period not in required range for employee hard constraint is invoked, which makes sure the number of consecutive weekends off in the period is not below the limit specified in consecutiveWeekendsOffMin.

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

3. Preferred consecutive weekends off per period

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

Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints.

Learn about constraint weights.
This rule is more likely to be satisfied for employees with a higher employee priority.

4. Weekends with period MONTH

When using the period MONTH with consecurive weekends off rules, if a weekend is included in 2 months, ie, Saturday is the last day of Jannuary and Sunday is the first day of February, the rule will only consider the day that belongs to the month being evaluated.

This can result in an employee being assigned to work on 1 of the weekend days (Saturday January 31st) but not the other (Sunday February 1st), and because Saturday 31st is not part of February, not being assigned a shift on February 1st would count as 1 of the consecutive weekends off.

In the following example, the employee might only have 1 day off in a weekend, but are still considered to have 2 consecutive weekends off, because the rule is evaluated within the bounds of a month.

For example, January 2026 ends on a Saturday and February 2026 starts the day after, on Sunday. If the consecutiveWeekendsOffMin is set to 2 and the period is set to "MONTH" (like in the example below) the solver may assign shifts to all but the 2 last weekends in January. In this case, the second to last weekend (Saturday 24 - Sunday 25) and the last weekend (Saturday 31) of January would count as 2 consecutive weekends worked even if there are shifts assigned on Sunday February 1.

Weekend of month date worked/off

1

Sat 3, Sun 4 January

worked

2

Sat 10, Sun 11 January

worked

3

Sat 17, Sun 18 January

worked

4

Sat 24, Sun 25 January

Off

5

Sat 31 January

Off

1

Sun 1 February

worked

 
{
  "periodRules": [
    {
      "id": "min2ConsecutiveWeekendsOff",
      "period": "MONTH",
      "consecutiveWeekendsOffLimit":
        {
          "consecutiveWeekendsOffMin": 2
        },
      "satisfiability": "REQUIRED",
    }
  ]
}

Next