Skip to main content
Many aspects that should be taken into consideration in producing a roster are only applicable during certain periods of time. For example, think of weekly limits for work, or the availability of employees during certain days of the week. Specifying such periods of time is done using the periods field. This page explains how to configure this field for different use cases.

Periods schema

​
periods
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.).

​
Periods created through days

The most basic way to define periods is to refer to specific days in the roster. This is done by using the days field in the periods object. Within this object, you can specify specific days using dates (in CALENDAR payloads) or dayIndices (in RECURRING payloads).
Referring to specific days using dates
{
  "periods": {
    "days": {
      "dates": ["2026-01-01", "2026-01-02", "2026-01-05"]
    }
  }
}

​
Days of the week

Alternatively, you can specify the days of the week using daysOfWeek. For example, the following periods definition will refer to all Wednesdays and Fridays in the roster.
Referring to specific days using days of week
{
  "periods": {
    "days": {
      "daysOfWeek": ["WED", "FRI"]
    }
  }
}

​
Start and end times

Finally, you can add a startTime and endTime to the days object to specify a time interval during the day. For example, the following periods definition will refer to all evenings on Wednesdays and Fridays. This could be useful for instance to specify that an employee is not available for work during these times (though they are still available for work earlier in these days).
Referring to specific days using days of week and time interval
{
  "periods": {
    "days": {
      "daysOfWeek": ["WED", "FRI"],
      "startTime": "18:00",
      "endTime": "23:00"
    }
  }
}
Creating periods through days will always consider each day in the roster as a separate period. This is relevant on some constraints where the targets of the constraint are applied to each period separately.

​
Periods created through custom definitions

If you need to create periods consisting of multiple days, you can use the customDefinitions field in the periods object. These are defined through a start and end day (and optionally a start and end time). For example, the following periods definition will refer to the period from January 1st to January 5th and the period from February 10th to February 14th.
Referring to a custom period using start and end days
{
  "periods": {
    "customDefinitions": [
      {
        "startDay": {
          "date": "2026-01-01"
        },
        "endDay": {
          "date": "2026-01-05"
        }
      },
      {
        "startDay": {
          "date": "2026-02-10"
        },
        "endDay": {
          "date": "2026-02-14"
        }
      }
    ]
  }
}

​
Start and end times

Similarly to the days field, you can also add a startTime and endTime to the customDefinitions object to specify a time interval during the day. For example, the following periods definition will refer to the period from 10:00 on January 1st to 18:00 on January 5th.
Referring to a custom period using start and end days and time interval
{
  "periods": {
    "customDefinitions": [
      {
        "startDay": {
          "date": "2026-01-01"
        },
        "endDay": {
          "date": "2026-01-05"
        },
        "startTime": "10:00",
        "endTime": "18:00"
      }
    ]
  }
}

​
Applying time to all days

Finally, custom period definitions allow you to choose whether the start and end time should apply to each day individually. For example, the following periods definition will refer to all periods of time between 20:00 and 06:00 on every day between January 1st and January 31st.
Referring to a custom period using start and end days and time interval and applying time to all days
{
  "periods": {
    "customDefinitions": [
      {
        "startDay": {
          "date": "2026-01-01"
        },
        "endDay": {
          "date": "2026-01-31"
        },
        "startTime": "20:00",
        "endTime": "06:00",
        "applyTimeToAllDays": true
      }
    ]
  }
}
By default, applyTimeToAllDays is set to false.

​
Periods created through recurrent definitions

If you want to create periods that are all the same length, the recurrentDefinition field might suit your needs. For example, if you want to create a constraint that applies on a weekly basis, the recurrent definition allows you to easily specify this without having to define each week by its exact start and end days. For example, the following recurrent definition will create a non-overlapping set of periods that are each 7 days long, starting from the first day and continuing until the last day of the roster.
Defining weekly periods using a recurrent definition
{
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7
    }
  }
}

​
Restricting the range of periods

If you only need your recurrent definition to create periods for a certain range within your roster, you can also specify the startDay and endDay properties. For example, the following recurrent definition will create a non-overlapping set of periods that are each 7 days long, starting from April 1st and continuing until June 30th.
Defining weekly periods for a specific range
{
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7,
      "startDay": {
        "date": "2026-04-01"
      },
      "endDay": {
        "date": "2026-06-30"
      }
    }
  }
}

​
Overlapping and non-consecutive periods

By default, periods created through a recurrent definition will be non-overlapping and consecutive. If you want to create a sliding window of periods, you can use the daysBetweenStarts property. For example, we could use the following periods on a constraint to make sure that an employee never works more than 40 hours in any 7-day period.
Defining weekly periods with a sliding window
{
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7,
      "daysBetweenStarts": 1
    }
  }
}

​
Start and end times

Recurrent definitions allow for the use of start and end time similarly to custom definitions. This example shows a recurrent definition for weekend periods that start Friday afternoon and last until Sunday night.
Defining weekend periods with a start and end time
{
  "periods": {
    "recurrentDefinition": {
      "startDay": {
        "date": "2026-01-02" // Start on the first Friday of the roster
      },
      "daysPerPeriod": 3, // Periods last Friday-Sunday
      "daysBetweenStarts": 7,
      "startTime": "18:00", // Starts at 6pm on Friday
      "endTime": "22:00" // Ends at 10pm on Sunday
    }
  }
}

​
Period labels

If there are periods that are useful in multiple constraints, you can define them in the labels property of the configuration. This can greatly reduce the size of your payloads when handled properly, and it can be smart to identify which periods are applicable for this within your integration.
Some commonly reused periods are for example weekends, weekdays, public holidays and nights.
The below example shows how to define labels for weekends and then reuse them on an employee availability constraint to make it undesirable for employees to work on weekends.
Defining labels for commonly reused periods
{
  "configuration": {
    "labels": {
      "periods": [
        {
          "label": "weekends",
          "periods": {
            "days": {
              "daysOfWeek": ["SAT", "SUN"]
            }
          }
        }
      ]
    }
  },
  "constraints": {
    "employeeAvailabilityConstraints": [
      {
        "id": "weekend-availabity",
        "importance": "HIGH",
        "isDesired": false,
        "periods": {
          "labels": ["weekends"]
        }
      }
    ]
  }
}