starts) and what should be avoided during that cooldown period (ends). This is useful for ensuring employees have adequate rest between demanding shifts, preventing burnout, and complying with labor regulations.
Constraint schema
object
Used to define required or desired rest between working shifts.
Show properties
Show properties
string
required
Unique identifier for the constraint.
array of string
Labels for the constraint. Labels can be used to group constraints together. For example, if multiple constraints are related to the same shift type, they can all be labeled with the same label.
string (enum: NONE | VERY_LOW | LOW | MEDIUM | HIGH | ...)
required
The importance of the constraint. The higher the importance, the more the solver will take the constraint into account. Under strict importance, the constraint may never be violated.
object
Show filters – properties
Show filters – properties
object
Used to filter which employees the constraint should be applied to. If not specified, the constraint applies to all employees.
Show employees – properties
Show employees – properties
array of string
List of employee ids that the constraint should be applied to.
array of string
List of employee labels that the constraint should be applied to.
object
Show matchTypes – properties
Show matchTypes – properties
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: “ANY”.
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: “ANY”.
object
Defines filtering for specific work that the constraint should be applied to. For example, it can be used to apply the constraint only to work carried out in specific roles.
Show work – properties
Show work – properties
object
Used to apply the constraint only to work carried out in specific roles.
Show roles – properties
Show roles – properties
array of string
List of relevant role ids.
object
Used to apply the constraint only to work carried out with specific workload categories.
Show workloads – properties
Show workloads – properties
array of string
If specified, the shift must have at least one of the workload categories specified in this list.
object
Defines the types of work that will trigger a cooldown. Currently, only filters on shifts are supported as starts.
Show starts – properties
Show starts – properties
object
Show shifts – properties
Show shifts – properties
array of string
List of shift ids that the constraint should be applied to. If not specified, no filtering is applied based on shift ids.
array of string
object
Show matchTypes – properties
Show matchTypes – properties
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: “ANY”.
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: “ANY”.
array of object
DEPRECATED.
Show filters – item structure
Show filters – item structure
string
required
The field to filter on. Can be “id” or “label”.
array of string
required
The values to filter on.
string (enum: NONE | ANY | ALL)
Defines how the values should be matched. For example, if set to ALL, an entity needs to have all of the specified values to match this filter. Default: “ANY”.
string (enum: NONE | ANY | ALL)
DEPRECATED. Default: “ANY”.
object
Defines the types of work that should be avoided during a cooldown. Currently, only filters on shifts are supported as ends.
Show ends – properties
Show ends – properties
object
Show shifts – properties
Show shifts – properties
array of string
List of shift ids that the constraint should be applied to. If not specified, no filtering is applied based on shift ids.
array of string
object
Show matchTypes – properties
Show matchTypes – properties
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: “ANY”.
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: “ANY”.
array of object
DEPRECATED.
Show filters – item structure
Show filters – item structure
string
required
The field to filter on. Can be “id” or “label”.
array of string
required
The values to filter on.
string (enum: NONE | ANY | ALL)
Defines how the values should be matched. For example, if set to ALL, an entity needs to have all of the specified values to match this filter. Default: “ANY”.
string (enum: NONE | ANY | ALL)
DEPRECATED. Default: “ANY”.
object
required
Defines the desired minimum duration of the cooldown. Can be defined in either hours or days.
Show targets – properties
Show targets – properties
object
List of periods in the schedule. Periods can either be defined explicitly using custom definitions, or through a recurrent definition. A recurrent definition can be used to easily generate a list of similar periods (such as weeks, months, etc.).
Show periods – properties
Show periods – properties
object
List of days in the schedule. Each day will become one period. By default, each period will last the entire day. If a startTime and/or endTime are specified, these will apply to each period.
Show days – properties
Show days – properties
array of date (date)
List of dates in the schedule. Only allowed in CALENDAR payloads.
array of dayIndex
List of day indices in the schedule. Only allowed in RECURRING payloads.
array of dayOfWeek
List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
array of object
List of custom period definitions. Each custom period definition defines one period in the schedule.
Show customDefinitions – item structure
Show customDefinitions – item structure
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show startDay – properties
Show startDay – properties
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show endDay – properties
Show endDay – properties
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
boolean
If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
object
A recurrent definition to easily create a set of similar periods.
Show recurrentDefinition – properties
Show recurrentDefinition – properties
integer
required
The number of days in each period.
integer
The number of days between the start of each period. If not specified, this defaults to the value of daysPerPeriod, creating non-overlapping consecutive periods. Setting daysBetweenStarts to 1 will create a sliding window of periods.
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show startDay – properties
Show startDay – properties
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show endDay – properties
Show endDay – properties
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
boolean
If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
array of string
Provide labels to re-use periods that were defined in the configuration.
Basic cooldown between shifts
The simplest use case is to require a minimum rest period between any two shifts. This ensures employees have adequate time to recover between work periods. When you omit thestarts and ends sections, the constraint applies to all shifts.
The below constraint requires a minimum of 12 hours of rest between any two shifts. After an employee finishes any shift, they cannot start another shift until at least 12 hours have passed.
{
"id": "cd-min-12h-rest",
"importance": "STRICT",
"targets": {
"minHours": 12
}
}
Cooldown between specific shift types
You can define cooldowns that only apply between specific types of shifts. For example, you might want a longer cooldown after night shifts before morning shifts.The below constraint requires at least 16 hours of rest after a night shift before an employee can work a morning shift. This helps ensure employees have adequate time to adjust their sleep schedule.
{
"id": "cd-night-to-morning",
"importance": "STRICT",
"starts": {
"shifts": {
"labels": ["night"]
}
},
"ends": {
"shifts": {
"labels": ["morning"]
}
},
"targets": {
"minHours": 16
}
}
Cooldown measured in days
Instead of specifying the cooldown in hours, you can specify it in days. This is useful for ensuring employees have full days off between certain types of work.The below constraint requires at least 2 days without a shift after working a weekend shift before an employee can work another weekend shift. This helps distribute weekend work more evenly among employees.
{
"id": "cd-weekend-2-days",
"importance": "STRICT",
"starts": {
"shifts": {
"labels": ["weekend"]
}
},
"ends": {
"shifts": {
"labels": ["weekend"]
}
},
"targets": {
"minDays": 2
}
}
Complex cooldown scenarios
You can create more complex cooldown rules by combining different shift types in thestarts and ends sections. This allows you to model sophisticated rest requirements.
The below constraint requires at least 48 hours of rest after working any intensive shift (like emergency shifts or long shifts) before an employee can work another intensive shift. This helps prevent employee burnout from demanding work.
{
"id": "cd-intensive-48h",
"importance": "STRICT",
"starts": {
"shifts": {
"labels": ["intensive"]
}
},
"ends": {
"shifts": {
"labels": ["intensive"]
}
},
"targets": {
"minHours": 48
}
}
Soft cooldown constraints
While cooldown constraints are often used withSTRICT importance to enforce mandatory rest periods, you can also use them with other importance levels to encourage (but not strictly require) rest periods.
The below constraint encourages (but doesn’t strictly require) at least 10 hours of rest after a night shift before an employee can work a morning shift. The solver will try to achieve this, but may violate it if necessary to satisfy other constraints.
{
"id": "cd-soft-night-to-morning",
"importance": "MEDIUM",
"starts": {
"shifts": {
"labels": ["night"]
}
},
"ends": {
"shifts": {
"labels": ["morning"]
}
},
"targets": {
"minHours": 10
}
}
Cooldown with specific shift IDs
You can also target specific shifts by their IDs, giving you fine-grained control over which shifts trigger cooldowns and which shifts are restricted during cooldown periods.The below constraint requires at least 8 hours of rest after a specific early morning shift (shift-1) before an employee can work a specific evening shift (shift-2). This is useful when you have specific shift pairs that should not be scheduled too close together.
{
"id": "cd-specific-shifts",
"importance": "STRICT",
"starts": {
"shifts": {
"ids": ["shift-1"]
}
},
"ends": {
"shifts": {
"ids": ["shift-2"]
}
},
"targets": {
"minHours": 8
}
}
Cooldown with filters
You can also limit a cooldown constraint to apply only to work carried out in specific roles.The below constraint requires a minimum of 16 hours of rest between any two shifts worked in role
role-1. Shifts worked in other roles are not considered by this constraint.{
"id": "cd-min-16h-rest-role-1",
"importance": "STRICT",
"filters": {
"work": {
"roles": {
"ids": ["role_1"]
}
}
},
"targets": {
"minHours": 16
}
}