> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vocabulary mapping

> Translate the vehicle-routing terms used in the literature and in other routing tools into the V3 fields that express them, and find where V3 has no such object

> [!NOTE]
>
> **V3 is in beta.** General availability (GA) is planned for January 2027.

The routing problem you modelled in a paper or in another tool is the same
one; only the words differ. This page maps the generic vocabulary to the V3
field that carries it, and names where V3 has no such object. The fields are
defined in [The V3 API model](https://docs.solvice.io/guides/vrp/v3/api-design.md) and
[Constraints](https://docs.solvice.io/guides/vrp/v3/constraints.md).

> [!WARNING]
>
> The schema is strict. A field carried over from another tool, such as
> `demand`, `skills` on a job, or `maxVisits`, is a `400` with an
> `unknown_field` item naming the key: it fails loudly instead of being ignored.
> See [Errors](https://docs.solvice.io/guides/vrp/v3/errors.md).

## Generic terms

Throughout, a **task** is a `jobs[]` or `shipments[]` entry.

| Term | What it usually means | In V3 | Notes |
| - | - | - | - |
| VRP | Vehicles leave a depot, visit customers, return | `problem` with `jobs`, `vehicles` and optional `shipments`, `depots`, `relations`, `objective`, `travel`, `quotas` | One request, one plan. A vehicle has one route per shift |
| CVRP | Customers have a demand; vehicles a capacity | `jobs[].pickup_load`, `jobs[].delivery_load`, `shipments[].load`; `vehicles[].capacity` | Named maps (`{ "weight": 30 }`), not positional arrays. At most 4 dimensions |
| VRPTW | Each customer has a hard service window | `time_windows[]` of `{ "from", "to" }` on jobs and shipment legs | Several windows per task; a window bounds the service start |
| Soft time window | Lateness is allowed at a price | `time_windows[].per_late_hour`, or fleet-wide `objective.per_late_hour` | Late side only; an early vehicle waits. A deadline is `target { at, on, per_late_hour }` |
| VRPPD | Goods go from a pickup to a delivery on one vehicle | `shipments[]` with `pickup`, `delivery` and `load` | Its own object, not two jobs plus a relation. One vehicle, pickup first |
| Multi-depot VRP | Vehicles are based at different depots | `shifts[].start` and `shifts[].end`: inline `location` or a `depot` id | Per shift, so a vehicle can start elsewhere on another day |
| Multi-trip VRP | A vehicle returns to a depot to reload mid-shift | `shifts[].reloads` (depot ids), `shifts[].max_trips`, `depots[].per_reload` | Capacity is enforced per trip. A reload is a `reload` stop in the response |
| Open VRP | Routes end at the last customer | Omit `shifts[].end` | Omit `start` too for a route that begins at the first task |
| Heterogeneous fleet | Vehicles differ in size, speed, cost or type | Per vehicle: `capacity`, `profile` (`car`, `truck`, `bike`), `speed_factor`, `service_factor`, `skills`, `costs` | Each resolves per vehicle, with `objective.costs` as the fleet default |
| Depot | Where vehicles start from and load | `depots[]`: a named place with `location`, `service_duration_s`, `per_reload` | A limited object: shifts reference it from `start`, `end` or `reloads`. It holds no stock; a job cannot point at it |
| Customer, stop, visit | One place to serve | `jobs[]` in the request; `routes[].stops[]` in the response | Response stops carry a `type`: `start`, `job`, `pickup`, `delivery`, `break`, `reload`, `end` |
| Demand | How much a customer needs | `delivery_load` (dropped off) or `pickup_load` (collected) | Direction is explicit: a delivery rides from the depot, a pickup to the end |
| Service time | Time on site | `service_duration_s`, plus `setup_duration_s` once per location | Scaled by `service_factor` and the task's `service_factors[]` |
| Precedence | A before B | `relations[]` of type `sequence`, `consecutive`, `tag_order` or `time_lag` | All relations are hard. `sequence` orders members sharing a route; add `same_route` to force one route |
| Skills | A qualification the vehicle must hold | `jobs[].required_skills[] { name, min_level }`; `vehicles[].skills[] { name, level }` | Objects, not bare strings. A shift's `skills` replaces the vehicle's |
| Vehicle eligibility | Only some vehicles may serve a task | `eligible_vehicles { allowed }` or `{ excluded }` | Hard. Soft: `preferences[] { vehicle, violation_cost }`; priced: `assignment_costs[] { vehicle, cost }` |
| Objective, weighted sum | Terms traded by weights | `objective.costs` rates in one currency, plus a priced field on each soft rule | No weights: every term is money and `score.components` itemises the total. Only `priority` ranks above cost |
| Penalty for unserved | Dropping a customer costs a penalty | `drop_cost` on the task | Without it a task is must-serve. `priority` ranks must-serve tasks; it never makes one droppable |
| Warm start, initial solution | Seed the search with a known plan | Request-level `plan`, the shape the response returns | `locked_count` freezes a dispatched prefix; `"pinned": true` keeps a stop on its vehicle |
| Dynamic re-optimisation | Re-plan as the day changes | Send the latest `plan` back to `solve`; `suggest` for new tasks; `evaluate` to score an edit | No state between calls: the plan travels in the request |
| Distance matrix | Travel times and distances between locations | `problem.travel { engine, departure_time }` | Fetched by Solvice: `osm`, `tomtom` or `straight_line`. No field for a matrix of your own |

## Coming from V2

The field-by-field mapping from the legacy V2 API, including the fields V3
does not carry over, is in [Migration from V2](https://docs.solvice.io/guides/vrp/v3/migration-from-v2.md).
When porting from any other tool, check the direction of its priority scale:
V3 `priority` is a rank from `1` up, and higher is more important.

Next: send the ported request to `POST /v3/routing/validate/solve`, which
returns the `400` a solve would, with a `pointer` per leftover field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.