Solution Explanation

The explanation endpoint provides detailed insights into your solution, including constraint violations and alternative assignment options.

Enable Explanation

Add the explanation option to your request:

{
  "employees": [
    {
      "name": "Alice",
      "skills": [{ "name": "bar" }]
    },
    {
      "name": "Bob",
      "skills": [{ "name": "kitchen" }]
    }
  ],
  "shifts": [
    {
      "name": "shift-1",
      "from": "2024-03-06T08:00:00",
      "to": "2024-03-06T17:00:00",
      "skills": [{ "name": "bar" }],
      "min": 1,
      "max": 1
    }
  ],
  "options": {
    "explanation": {
      "enabled": true
    }
  }
}

Solution Response

The solver assigns shift-1 to Alice since she has the required bar skill:

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -1,
    "feasible": true
  },
  "assignments": [
    {
      "shift": "shift-1",
      "from": "2024-03-06T08:00:00",
      "to": "2024-03-06T17:00:00",
      "skills": ["bar"],
      "employee": "Alice"
    }
  ]
}

Unserved Reasons

When explanation is enabled, unassigned shifts also get their blocking hard constraints reported directly on the solve response via unservedReasons:

{
  "unassigned": ["shift-2"],
  "unservedReasons": {
    "shift-2": ["Employee Skill Match"]
  }
}

unservedReasons is only populated when options.explanation.enabled is true.

Explanation Response

Request the explanation from /v2/fill/jobs/{id}/explanation:

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -1,
    "feasible": true
  },
  "conflicts": [
    {
      "constraint": "Employee Skill Level Match Soft",
      "score": "-1soft",
      "employee": "Alice",
      "shift": "shift-1",
      "description": "Soft skill-level mismatch"
    }
  ],
  "unresolved": [
    {
      "constraint": "Employee Skill Level Match Soft",
      "score": "-1soft"
    }
  ]
}

conflicts

array

Individual constraint violations contributing to the score

conflicts.description

string

Human-readable description of the violated constraint

conflicts.relation

string

Related shift id, e.g. the second shift of a minimum-rest conflict

unresolved

array

Aggregated constraints that could not be fully satisfied

Alternative Assignments

When explanation is enabled, the solver evaluates all possible employee-shift combinations:

{
  "alternatives": {
    "shift-1": [
      {
        "shift": "shift-1",
        "employee": "Alice",
        "score": {
          "hardScore": 0,
          "mediumScore": 0,
          "softScore": -1,
          "feasible": true
        },
        "violations": [
          {
            "constraint": "Employee Skill Level Match Soft",
            "score": "-1soft"
          }
        ]
      },
      {
        "shift": "shift-1",
        "employee": "Bob",
        "score": {
          "hardScore": -1,
          "mediumScore": 0,
          "softScore": -1,
          "feasible": false
        },
        "violations": [
          {
            "constraint": "Employee Skill Match",
            "score": "-1hard"
          },
          {
            "constraint": "Employee Skill Match Soft",
            "score": "-1soft"
          }
        ]
      }
    ]
  }
}

The alternatives show that assigning Bob would violate a hard constraint (skill mismatch), explaining why Alice was chosen.

Explanation Options

options.explanation.enabled

boolean

default:"false"

Enable post-processing to generate alternatives for each assignment

options.explanation.filterHardConstraints

boolean

default:"false"

Exclude alternatives that violate hard constraints from the response

options.explanation.onlyUnassigned

boolean

default:"false"

Compute alternatives only for shifts left unassigned, skipping already-filled shifts to reduce response size and solve time on large problems

Use Cases

Scenario	How Explanation Helps
Debugging	Identify why a solution is infeasible
User transparency	Show managers why specific assignments were made
What-if analysis	Evaluate impact of assigning different employees
Constraint tuning	Understand which constraints drive the solution

Use filterHardConstraints: true to only see viable alternatives, reducing response size for large problems.

Platform

VRP API

Fill API

Enable Explanation

Solution Response

Unserved Reasons

Explanation Response

Alternative Assignments

Explanation Options

Use Cases

​Enable Explanation

​Solution Response

​Unserved Reasons

​Explanation Response

​Alternative Assignments

​Explanation Options

​Use Cases

Enable Explanation

Solution Response

Unserved Reasons

Explanation Response

Alternative Assignments

Explanation Options

Use Cases