Validation

Whenever you submit a dataset to Timefold through the API the input is validated and if there are issues, you will see the following depending on the type of validation issue:

  • Invalid JSON: The submitted JSON file is validated to make sure the JSON is valid according to the OpenAPI specification and can be processed by Timefold.

A POST call with an invalid JSON document will return a status 400 Bad Request. The response will include a message specifying the input JSON has an invalid format and details that will help you locate the issue with the JSON.

Solution: Fix the invalid JSON and resubmit the dataset.

  • Error: The JSON is valid according to the OpenAPI specification but the submitted dataset includes (or does not include) elements that need to be rectified before the dataset can be solved, including:

    1. Referencing an undeclared tag type or tag.

    2. A shift group matches multiple shift group rules with assignment mode defined. Only one rule with assignment mode per shift group is allowed.

    3. A shift belongs to multiple shift groups. A shift can only belong to one shift group.

    4. Start times must be earlier than end times.

    5. A shift’s logged time must not be negative or longer than the duration of the shift.

    6. An employee can only have 1 contract with travel configurations.

    7. An employee must have a location if they are assigned a contract with a travel configuration.

    8. An employee can only have 1 contract with a custom FTE configuration.

    9. Either the maxEmployeeToShiftTravelDistanceInMeters or the minMinutesBetweenShiftsInDifferentLocations must be set on the travelConfiguration of a contract.

    10. A shift matches multiple rotation groups. A shift can only belong to one rotation group.

    11. A contract defines non-consecutive weekend days in weekendConfiguration. Weekend days must be consecutive.

    12. An employee defines a pairing with themself.

    13. Minimums must be less than their associated maximums, for instance, minDemand and maxDemand, shiftsWorkedMin and shiftsWorkedMax.

    14. Rules use an invalid period that is not a built-in period or a custom period.

Solution: Review the error message and update the dataset.

  • Warning: The JSON is valid according to the OpenAPI specification but the dataset:

    1. Uses a deprecated feature.

    2. Is missing some element that is necessary to successfully assign a shift, including:

      1. The planning window cannot be determined because there are no shifts.

      2. The list of shifts is empty.

      3. The list of employees is empty.

      4. An employee defines both a required and prohibited pairing with another employee.

      5. A multi-day shift pattern rule starts with OFF but the planning window was not provided.

      6. A rolling window rule on a contract has a daysWorkedLimit with a daysWorkedMax greater than the rolling window size in full days.

      7. A rolling window rule on a contract has a minutesWorkedLimit with a minutesWorkedMax greater than the rolling window size in minutes.

      8. A shift requires or prefers a skill that is not defined by any employee.

Solution: The dataset will be processed, but we recommend looking at the warnings and updating the dataset.