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, for instance:

    1. A visit time window does not have a minStartTime that is less than or equal to the maxStartTime or maxEndTime.

    2. A floating break does not have a minStartTime plus duration that is less than or equal to the maxEndTime.

    3. A fixed break does not have a startTime less than or equal to the endTime.

    4. A break starts before its shift minStartTime.

    5. A vehicle shift must have either a minStartTime or a minFirstVisitArrivalTime.

    6. A visit dependency must reference an existing preceding visit id.

    7. A visit group must have at least two visits.

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 visit, including:

      1. Technician ratings are defined for vehicles, but the model config does not enable the technician ratings constraint.

      2. There is a deprecated priority in a visit.

      3. The list of vehicles is empty.

      4. The list of vehicle shifts is empty.

      5. A vehicle shift should have a maxSoftTravelTime that is less or equal to maxTravelTime.

      6. The time window is too small for the visit’s specified duration.

      7. All time windows of a visit start after the latestSlaEndTime.

      8. A visit’s 'preferredVehicles' references a non-existing vehicle.

      9. A visit’s 'prohibitedVehicles' references a non-existing vehicle.

      10. A visit requires a tag that is not declared by any vehicle shift. This visit cannot be assigned to any vehicle shift.

      11. A visit requires a skill that is not declared by any vehicle shift. This visit cannot be assigned to any vehicle shift.

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