Rules and Constraints

Rules let you set constraints on working days, hours, and shift sequences. Use rules to enforce labor regulations, contractual limits, and scheduling policies.

Rule Types

Constraint	Description
`COUNTER`	Count occurrences within a period (days worked, hours, shifts)
`SEQUENCE`	Limit consecutive occurrences (max days in a row)

Counter Rules

Count and limit occurrences within a planning period.

Working Days

Limit total working days:

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "DAYS_WORKED",
      "min": 2,
      "max": 4
    }
  ]
}

Days Idle

Ensure minimum days off:

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "DAYS_IDLE",
      "min": 1,
      "max": 2,
      "period": { "duration": "P7D" }
    }
  ]
}

Weekends Idle

Guarantee free weekends:

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "WEEKENDS_IDLE",
      "min": 1,
      "max": 2,
      "period": { "duration": "P28D" }
    }
  ]
}

Requires weekend definition in options to specify what constitutes a weekend.

Shift Type Limits

Limit specific shift types using tags:

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "SHIFT_TYPES_WORKED",
      "shifts": ["NIGHT"],
      "max": 3
    }
  ]
}

Maximum Consecutive Days

Cap the number of consecutive working days:

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "MAX_CONSECUTIVE_DAYS",
      "max": 5
    }
  ]
}

Counter Types

Type	Description
`DAYS_WORKED`	Total days with at least one shift
`DAYS_IDLE`	Total days without any shift
`WEEKENDS_WORKED`	Complete weekends with work
`WEEKENDS_IDLE`	Complete weekends without work
`SHIFT_TYPES_WORKED`	Shifts matching specific tags
`SHIFT_TYPES_HOURS_WORKED`	Hours worked on shifts matching specific tags
`HOURS_WORKED`	Total hours across all shifts
`MAX_CONSECUTIVE_DAYS`	Maximum number of consecutive working days (COUNTER requires `max`)

DAYS_IDLE and WEEKENDS_IDLE require a period (either a fixed from/to range or a duration) to be specified — without one, the rule is silently ignored and never affects the schedule.

Period Scoping

By default, rules apply to the entire planning period. Scope rules to specific periods:

Fixed Period

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "SHIFT_TYPES_WORKED",
      "shifts": ["NIGHT"],
      "max": 3,
      "period": {
        "from": "2024-03-06T08:00:00",
        "to": "2024-03-10T17:00:00"
      }
    }
  ]
}

Fixed-Length Windows

period.duration splits the planning horizon into consecutive, non-overlapping blocks of the given length, starting at the horizon’s start date (e.g. P3D over a 14-day horizon produces four 3-day blocks plus one 2-day clamped block). Each block is scored independently:

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "SHIFT_TYPES_WORKED",
      "shifts": ["NIGHT"],
      "max": 3,
      "period": {
        "duration": "P3D"
      }
    }
  ]
}

This is not a true rolling/sliding window, so violations spanning a block boundary are not caught. Align period.duration (e.g. P7D) to your planning horizon’s start date for a weekly cap. For a true any-N-day rolling check, this feature does not currently support it.

Sequence Rules

Limit consecutive occurrences without specifying a period window.

Consecutive Working Days

{
  "rules": [
    {
      "constraint": "SEQUENCE",
      "type": "DAYS_WORKED",
      "min": 2,
      "max": 4
    }
  ]
}

Employees work between 2 and 4 consecutive days before a day off.

Maximum Consecutive Days

{
  "rules": [
    {
      "constraint": "SEQUENCE",
      "type": "MAX_CONSECUTIVE_DAYS",
      "max": 5
    }
  ]
}

Conditional Rules

Trigger a rule when another rule’s threshold is exceeded. Example: If 20+ hours of night shifts within 72 hours, then require 2 days idle:

{
  "rules": [
    {
      "constraint": "COUNTER",
      "type": "HOURS_WORKED",
      "period": {
        "duration": "PT72H"
      },
      "max": 19,
      "shifts": ["NIGHT"],
      "then": {
        "constraint": "SEQUENCE",
        "type": "DAYS_IDLE",
        "min": 2
      }
    }
  ]
}

Use max to trigger on “N or more”; use min to trigger on “fewer than N”.

Conditional rules can create complex constraints. Test thoroughly to avoid making problems infeasible.

Rule Properties

constraint

string

required

Rule type: COUNTER or SEQUENCE

type

string

required

What to count or sequence (see tables above)

min

integer

Minimum count or sequence length

max

integer

Maximum count or sequence length

shifts

array

Filter rule to specific shift tags

period

object

Time scope with from/to dates, or a fixed-length duration that tiles the planning horizon into non-overlapping blocks

then

Rule

Conditional rule triggered when this rule is exceeded. The then rule always inherits the parent rule’s resolved period window (including any rolling-window expansion); any period set directly on the then object is ignored.

Common Rule Patterns

40-hour work week

{
  "constraint": "COUNTER",
  "type": "HOURS_WORKED",
  "min": 32,
  "max": 40,
  "period": { "duration": "P7D" }
}

Maximum 5 consecutive days

{
  "constraint": "SEQUENCE",
  "type": "DAYS_WORKED",
  "max": 5
}

At least 2 weekends off per month

{
  "constraint": "COUNTER",
  "type": "WEEKENDS_IDLE",
  "min": 2,
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  }
}

Max 2 night shifts per week

{
  "constraint": "COUNTER",
  "type": "SHIFT_TYPES_WORKED",
  "shifts": ["NIGHT"],
  "max": 2,
  "period": { "duration": "P7D" }
}

Platform

VRP API

Fill API

Rule Types

Counter Rules

Working Days

Days Idle

Weekends Idle

Shift Type Limits

Maximum Consecutive Days

Counter Types

Period Scoping

Fixed Period

Fixed-Length Windows

Sequence Rules

Consecutive Working Days

Maximum Consecutive Days

Conditional Rules

Rule Properties

Common Rule Patterns

​Rule Types

​Counter Rules

​Working Days

​Days Idle

​Weekends Idle

​Shift Type Limits

​Maximum Consecutive Days

​Counter Types

​Period Scoping

​Fixed Period

​Fixed-Length Windows

​Sequence Rules

​Consecutive Working Days

​Maximum Consecutive Days

​Conditional Rules

​Rule Properties

​Common Rule Patterns

Rule Types

Counter Rules

Working Days

Days Idle

Weekends Idle

Shift Type Limits

Maximum Consecutive Days

Counter Types

Period Scoping

Fixed Period

Fixed-Length Windows

Sequence Rules

Consecutive Working Days

Maximum Consecutive Days

Conditional Rules

Rule Properties

Common Rule Patterns