{ "openapi" : "3.0.1", "info" : { "title" : "DNA Evolutions - JOpt.TourOptimizer", "description" : "# JOpt.TourOptimizer REST API\n\n![DNA Evolutions Logo](https://www.dna-evolutions.com/images/dna_logo.png)\n\nJOpt.TourOptimizer is DNA Evolutions' route optimization and scheduling engine for transportation, field service, and resource planning scenarios.\n\nThis API is a **reactive Spring WebFlux REST service** with an **OpenAPI 3** contract, designed for integration into third-party systems and for generating typed client SDKs directly from the schema.\n\n---\n\n## Endpoint groups\n\n### Job endpoints (`job`)\n\nThe primary integration model for all deployments with a connected database.\n\nSubmit an optimization job with `POST /api/v1/jobs` and receive an HTTP 202 response containing a unique `jobId`. Use that jobId to poll for status, progress, warnings, errors, and the final result at any time — no open connection required.\n\n| Endpoint | Description | Availability |\n|---|---|---|\n| `POST /api/v1/jobs` | Submit an async optimization job | All deployments |\n| `GET /api/v1/jobs/{jobId}/status` | Poll job status | All deployments |\n| `GET /api/v1/jobs/{jobId}/result` | Retrieve full optimization result | All deployments |\n| `GET /api/v1/jobs/{jobId}/solution` | Retrieve solution payload only | All deployments |\n| `GET /api/v1/jobs/{jobId}/progress` | Retrieve progress snapshots | All deployments |\n| `GET /api/v1/jobs/{jobId}/warnings` | Retrieve warning messages | All deployments |\n| `GET /api/v1/jobs/{jobId}/errors` | Retrieve error messages | All deployments |\n| `GET /api/v1/jobs/{jobId}/export` | Download result as ZIP archive | All deployments |\n| `POST /api/v1/jobs/{jobId}/stop` | Send graceful stop signal to a running job | All deployments |\n| `DELETE /api/v1/jobs/{jobId}` | Delete all persisted data for a job | All deployments |\n| `POST /api/v1/jobs/search` | Search jobs by metadata criteria | On-premise (free-search enabled) |\n| `POST /api/v1/jobs/import` | Import a pre-computed result directly | On-premise (import enabled) |\n\nAll job endpoints require the `X-Tenant-Id` header, injected by the API gateway. The `jobId` returned at submission is the only token needed for all subsequent reads.\n\n### Synchronous run endpoints (`optimization`)\n\nAvailable on on-premise installations with synchronous mode enabled. The client holds the HTTP connection open and receives the result directly in the response body.\n\n| Endpoint | Description |\n|---|---|\n| `POST /api/v1/runs` | Start a run, return runId immediately (HTTP 202) |\n| `GET /api/v1/runs/{runId}/result` | Block until run completes, return full result |\n| `GET /api/v1/runs/{runId}/solution` | Block until run completes, return solution only |\n| `DELETE /api/v1/runs/{runId}` | Stop the run gracefully |\n| `GET /api/v1/runs/{runId}/started` | One-shot signal when the run has started |\n\n### Event stream endpoints (`stream`)\n\nServer-Sent Event streams for monitoring a running synchronous optimization in near real time. Subscribe to one or more streams while a `POST /api/v1/runs` call is in progress.\n\n| Endpoint | Event type |\n|---|---|\n| `GET /api/v1/runs/{runId}/stream/progress` | Progress percentage and timing |\n| `GET /api/v1/runs/{runId}/stream/status` | Lifecycle status transitions |\n| `GET /api/v1/runs/{runId}/stream/warnings` | Non-fatal solver warnings |\n| `GET /api/v1/runs/{runId}/stream/errors` | Solver error events |\n\n### Health endpoint (`health`)\n\n| Endpoint | Description |\n|---|---|\n| `GET /api/v1/health` | Service liveness and readiness |\n\n---\n\n## Deployment modes and feature flags\n\nEndpoints that require specific conditions are activated via Spring `@Conditional` annotations and application properties. Endpoints not active in a given deployment are absent from the service entirely and do not appear in the runtime spec.\n\n| Condition | Property / annotation | Effect |\n|---|---|---|\n| Database connected | `DatabaseEnabledCondition` | Activates all `job` endpoints |\n| Sync mode | `SynchControllersEnabledCondition` | Activates `optimization` and `stream` endpoints |\n| Free search | `DatabaseFreeSearchEnabledCondition` | Activates `POST /api/v1/jobs/search` |\n| Import | `DatabaseJobImportEnabledCondition` | Activates `POST /api/v1/jobs/import` |\n\n---\n\n## Tenant isolation\n\nEvery job endpoint is scoped by `X-Tenant-Id`, injected by the API gateway. Persisted documents are tagged with both `jobId` and `tenantId`. A request with a valid `jobId` but a mismatched `tenantId` returns no data. The `jobId` is a UUID v4 (122 bits of randomness) and is not a security credential — security is enforced by the verified `tenantId` from the gateway header.\n\n---\n\n## Encryption at rest\n\nResults can be stored encrypted in two modes:\n\n- **CLIENT mode**: key derived from a caller-provided passphrase via PBKDF2. Pass the same secret in `X-Encryption-Secret` when reading back.\n- **KMS mode**: server-generated data encryption key (DEK) wrapped by an external key management service (Azure Key Vault, AWS KMS). Decryption is transparent to the caller.\n\nThe `encrypted` and `sec` fields in `DatabaseInfoSearchResult` indicate which mode was used for each stored result.\n\n---\n\n## Client generation\n\nThe OpenAPI schema can be used to generate typed clients for any language. The `operationId` values follow `{verb}{Resource}` lowerCamelCase convention (`createJob`, `getJobResult`, `listJobs`, etc.) for predictable generated method names.\n\n---\n\nThis service is based on **JOpt Core (7.5.3-rc2-j17)**.\n", "contact" : { "name" : "DNA Evolutions GmbH", "url" : "https://dna-evolutions.com", "email" : "info@dna-evolutions.com" }, "version" : "1.3.5-SNAPSHOT", "x-logo" : { "url" : "https://www.dna-evolutions.com/images/dna_logo.png", "altText" : "DNA Evolutions", "href" : "https://dna-evolutions.com", "backgroundColor" : "#FFFFFF" } }, "externalDocs" : { "description" : "DNA Evolutions documentation hub", "url" : "https://dna-evolutions.com/docs/getting-started/home/introduction" }, "servers" : [ { "url" : "/", "description" : "TourOptimizer service endpoint" } ], "tags" : [ { "name" : "job", "description" : "Async job lifecycle. Submit an optimization with POST /api/v1/jobs and receive a jobId. Use that jobId to poll status, retrieve results, download exports, stop a running job, and delete persisted data. Stop and delete are intentionally separate operations: POST /api/v1/jobs/{jobId}/stop sends a graceful stop signal and returns immediately, while DELETE /api/v1/jobs/{jobId} removes all persisted artifacts and should only be called after the job has terminated. Search and import endpoints are available on on-premise installations with the respective feature flags enabled. All endpoints require the X-Tenant-Id header." }, { "name" : "optimization", "description" : "Synchronous blocking optimization. On-premise only (SynchControllersEnabledCondition). POST /api/v1/runs starts an optimization and returns HTTP 202 with a runId immediately. Multiple concurrent runs are fully supported — each run is isolated by its runId. GET /api/v1/runs/{runId}/result blocks until the optimizer finishes and returns the full result. GET /api/v1/runs/{runId}/solution blocks until done and returns the solution payload only. DELETE /api/v1/runs/{runId} requests a graceful early termination. GET /api/v1/runs/{runId}/started emits once when the run transitions to active. Intended for short optimizations; use the job endpoints for long-running scenarios." }, { "name" : "stream", "description" : "Server-Sent Event streams. On-premise only (SynchControllersEnabledCondition). Each stream is scoped to a specific runId returned by POST /api/v1/runs. Subscribe to GET /api/v1/runs/{runId}/stream/* while the run is in progress to receive live progress percentages, lifecycle status transitions, non-fatal warnings, and solver error events. Concurrent runs each have independent, isolated stream subscriptions." }, { "name" : "health", "description" : "Service liveness and readiness. GET /api/v1/health returns the current health status of this endpoint. Always available regardless of database or sync mode configuration." } ], "paths" : { "/api/v1/runs" : { "post" : { "tags" : [ "optimization" ], "summary" : "Start an optimization run and return a runId.", "description" : "Starts a synchronous optimization and returns HTTP 202 with a runId. Intended for short optimizations that complete within a few minutes. The result connection will time out after 10 minutes. For long-running optimizations use POST /api/v1/jobs instead, which provides async job tracking without holding an HTTP connection open.", "operationId" : "startRun", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RestOptimization" } } }, "required" : true }, "responses" : { "202" : { "description" : "Run accepted and started. Use the runId with the companion endpoints.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunAcceptedResponse" } } } }, "401" : { "description" : "Unauthorized: license not valid or element limit exceeded.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } }, "500" : { "description" : "Internal server error during optimization setup.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/runs/{runId}/stream/warnings" : { "get" : { "tags" : [ "stream", "optimization" ], "summary" : "SSE stream of optimization warnings for a run.", "description" : "Subscribe to receive warning events for the run identified by runId. Warnings indicate non-fatal issues such as unserviceable nodes or soft constraint violations.", "operationId" : "streamWarnings", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "OK", "content" : { "text/event-stream" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/JOptOptimizationWarning" } } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/runs/{runId}/stream/status" : { "get" : { "tags" : [ "stream", "optimization" ], "summary" : "SSE stream of optimization status messages for a run.", "description" : "Subscribe to receive status lifecycle events for the run identified by runId (e.g. STARTED, RUNNING, FINISHED).", "operationId" : "streamStatus", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "OK", "content" : { "text/event-stream" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/JOptOptimizationStatus" } } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/runs/{runId}/stream/progress" : { "get" : { "tags" : [ "stream", "optimization" ], "summary" : "SSE stream of optimization progress for a run.", "description" : "Subscribe to receive real-time progress updates for the run identified by runId. Each event contains the current progress percentage and timing information.", "operationId" : "streamProgress", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "OK", "content" : { "text/event-stream" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/JOptOptimizationProgress" } } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/runs/{runId}/stream/errors" : { "get" : { "tags" : [ "stream", "optimization" ], "summary" : "SSE stream of optimization errors for a run.", "description" : "Subscribe to receive error events for the run identified by runId. Errors indicate serious problems that may affect result quality.", "operationId" : "streamErrors", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "OK", "content" : { "text/event-stream" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/JOptOptimizationError" } } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/runs/{runId}/started" : { "get" : { "tags" : [ "optimization", "stream" ], "summary" : "Emits once the run has transitioned to the running state.", "description" : "Returns a single boolean true when the optimizer for the given runId transitions to the running state. Useful for clients that want to begin subscribing to event streams only after the optimizer has actually started.", "operationId" : "getStartedSignal", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Optimization has started.", "content" : { "application/json" : { "schema" : { "type" : "boolean" } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/runs/{runId}/solution" : { "get" : { "tags" : [ "optimization" ], "summary" : "Retrieve the solution of a run (blocks until complete).", "description" : "Blocks the connection until the optimization identified by runId finishes, then returns the Solution payload only, omitting full optimization metadata. Returns 404 if the runId is unknown or the run has already completed.", "operationId" : "getRunSolution", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Optimization finished. Solution payload returned.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Solution" } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } }, "500" : { "description" : "Internal server error during optimization.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } }, "504" : { "description" : "Gateway timeout: optimization exceeded the configured time limit.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/runs/{runId}/result" : { "get" : { "tags" : [ "optimization" ], "summary" : "Retrieve the full result of a run (blocks until complete).", "description" : "Blocks the connection until the optimization finishes or the timeout is reached. Returns 504 if the optimizer has not finished within the connection timeout. If you expect runs longer than a few minutes, use POST /api/v1/jobs instead.", "operationId" : "getRunResult", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Optimization finished. Full RestOptimization result returned.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RestOptimization" } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } }, "500" : { "description" : "Internal server error during optimization.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } }, "504" : { "description" : "Gateway timeout: optimization exceeded the configured time limit.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } }, "/api/v1/health" : { "get" : { "tags" : [ "health" ], "summary" : "Get the health status of this service.", "description" : "Returns the current health status reported by Spring Boot Actuator. HTTP 200 indicates the service is UP and ready to accept requests. HTTP 503 indicates the service is DOWN, OUT_OF_SERVICE, or in an UNKNOWN state.", "operationId" : "getHealth", "responses" : { "200" : { "description" : "Service is UP.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Status" } } } }, "503" : { "description" : "Service is DOWN, OUT_OF_SERVICE, or UNKNOWN.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Status" } } } } } } }, "/api/v1/runs/{runId}" : { "delete" : { "tags" : [ "optimization", "stream" ], "summary" : "Stop an active optimization run gracefully.", "description" : "Requests a graceful stop of the run identified by runId. The optimizer finishes its current iteration and emits the best result found so far, which is then returned by the blocking GET result endpoint. Returns 404 if the runId is unknown or already completed.", "operationId" : "stopRun", "parameters" : [ { "name" : "runId", "in" : "path", "description" : "Run identifier returned by POST /api/v1/runs.", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Stop signal accepted. The run will terminate shortly.", "content" : { "application/json" : { "schema" : { "type" : "boolean" } } } }, "404" : { "description" : "No active run found for this runId.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } } } } }, "components" : { "schemas" : { "AbsoluteNodeColorCapacity" : { "required" : [ "maxUsage", "minUsage", "nodeColor" ], "type" : "object", "properties" : { "nodeColor" : { "$ref" : "#/components/schemas/NodeColor" }, "minUsage" : { "type" : "integer", "description" : "The minimum number of nodes of this color that must appear on a route for the constraint to be satisfied.", "format" : "int32" }, "maxUsage" : { "type" : "integer", "description" : "The maximum number of nodes of this color permitted on a single route.", "format" : "int32" } }, "description" : "The per-color capacity limits (absolute count-based) enforced by this multi-route constraint." }, "AbsoluteNodeColorMultiRouteConstraint" : { "required" : [ "absoluteNodeColorCapacities", "mirrorItem", "typeName" ], "type" : "object", "description" : "A multi-route constraint that enforces per-color capacity limits across multiple working hours of a resource, using absolute (count-based) limits.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "mirrorItem" : { "$ref" : "#/components/schemas/IntegerMultiConstraintHelperItem" }, "absoluteNodeColorCapacities" : { "type" : "array", "description" : "The per-color capacity limits (absolute count-based) enforced by this multi-route constraint.", "items" : { "$ref" : "#/components/schemas/AbsoluteNodeColorCapacity" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "AbsoluteNodeColorMultiRouteConstraint", "default" : "AbsoluteNodeColorMultiRouteConstraint" } } } ] }, "AnyDef" : { "type" : "object", "description" : "Composite date predicate that matches when ANY of the contained timeDefs match (logical OR). Each entry in timeDefs can be any concrete DateDef subtype. typeName must be \"Any\".", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "timeDefs" : { "type" : "array", "description" : "List of date predicates evaluated with OR logic. The containing AnyDef matches if at least one entry matches.", "items" : { "oneOf" : [ { "$ref" : "#/components/schemas/AnyDef" }, { "$ref" : "#/components/schemas/Day" }, { "$ref" : "#/components/schemas/DayMonth" }, { "$ref" : "#/components/schemas/DayMonthYear" }, { "$ref" : "#/components/schemas/RangeDay" }, { "$ref" : "#/components/schemas/RangeDayMonth" }, { "$ref" : "#/components/schemas/RangeDayMonthYear" }, { "$ref" : "#/components/schemas/RangeWeekDay" }, { "$ref" : "#/components/schemas/WeekDay" } ] } } } } ] }, "BindingResourceConstraint" : { "required" : [ "resources", "typeName" ], "type" : "object", "description" : "A node constraint that binds specific resources as the only eligible visitors. Only the listed resources may visit this node (hard) or are preferred with penalty for others (soft). Priority determines preference order among bound resources.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "resources" : { "type" : "array", "description" : "The resources that can be choosen to visit a certain node.", "items" : { "$ref" : "#/components/schemas/ResourceWithPriority" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "BindingResource", "default" : "BindingResource" } } } ] }, "BitTypeConstraint" : { "required" : [ "typeName", "typeNames" ], "type" : "object", "description" : "A high-performance bitset-based skill constraint on a node. Type names are integer identifiers matched via bitwise operations against BitTypeQualification on resources. Functionally equivalent to TypeConstraint but significantly faster for large type sets.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "typeNames" : { "type" : "array", "description" : "A list of user-provided type-integer numbers. A Constraint type name must match to a Qualification type name to result in a violation free solution.", "items" : { "type" : "string", "description" : "A list of user-provided type-integer numbers. A Constraint type name must match to a Qualification type name to result in a violation free solution." } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "BitType", "default" : "BitType" } } } ] }, "BitTypeQualification" : { "required" : [ "typeName", "typeNames" ], "type" : "object", "description" : "A high-performance bitset-based skill qualification. Declares type names as integer identifiers that are matched via bitwise operations against BitTypeConstraint on nodes. Significantly faster than string-based matching for large-scale problems with many skill types.", "allOf" : [ { "$ref" : "#/components/schemas/QualificationType" }, { "type" : "object", "properties" : { "typeNames" : { "type" : "array", "description" : "A list of user-provided type-names. A Constraint type name must match to a Qualification type number (integer) to result in a violation free solution.", "items" : { "type" : "string", "description" : "A list of user-provided type-names. A Constraint type name must match to a Qualification type number (integer) to result in a violation free solution." } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "BitType", "default" : "BitType" } } } ] }, "BitTypeWithExpertiseConstraint" : { "required" : [ "isHardLevel", "typeName" ], "type" : "object", "description" : "A bitset-based skill constraint with expertise levels on nodes. Each required type maps to a TypeLevelRequirement specifying the minimum expertise level. Supports cost models that penalize over- or under-qualified assignments. Matched against BitTypeWithExpertiseQualification on resources.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "dictTypeNames" : { "type" : "array", "description" : "A list of user-provided dict type-names. Those values will be mapped.", "items" : { "type" : "string", "description" : "A list of user-provided dict type-names. Those values will be mapped." } }, "dictMapping" : { "type" : "object", "additionalProperties" : { "$ref" : "#/components/schemas/TypeLevelRequirement" }, "description" : "The mapping of a certain type. or multiple types" }, "infoCostModel" : { "type" : "string", "description" : "The cost model for matching the expertise.", "enum" : [ "PENALIZE_MATCHING_SKILL_HIGH_DELTA", "PENALIZE_MATCHING_SKILL_PREFERRED_RESOURCE_HIGH_DELTA", "PENALIZE_MATCHING_SKILL_LOW_DELTA", "PENALIZE_MATCHING_SKILL_PREFERRED_RESOURCE_LOW_DELTA", "NO_PENALIZE_MATCHING_SKILL" ] }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "BitTypeWithExpertise", "default" : "BitTypeWithExpertise" }, "isHardLevel" : { "type" : "boolean", "description" : "Defines if a level of a cosntraint is soft contrained or hard constraint. A hard constraint is fullfilled by the architectural design of the Optimzer. Therefore a hard constraint violation cannot occure. However, not all constraints can be hard-constraint-" } } } ] }, "BitTypeWithExpertiseQualification" : { "required" : [ "typeName" ], "type" : "object", "description" : "A bitset-based skill qualification with expertise levels. Each type maps to a TypeLevelOffering declaring the resource's expertise level. Matched against BitTypeWithExpertiseConstraint on nodes, which can require minimum expertise levels and apply cost models.", "allOf" : [ { "$ref" : "#/components/schemas/QualificationType" }, { "type" : "object", "properties" : { "dictTypeNames" : { "type" : "array", "description" : "A list of user-provided dict type-names. Those values will be mapped.", "items" : { "type" : "string", "description" : "A list of user-provided dict type-names. Those values will be mapped." } }, "dictMapping" : { "type" : "object", "additionalProperties" : { "$ref" : "#/components/schemas/TypeLevelOffering" }, "description" : "The mapping of a certain type. or multiple types" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "BitTypeWithExpertise", "default" : "BitTypeWithExpertise" } } } ] }, "CapacityResource" : { "required" : [ "typeName" ], "type" : "object", "description" : "The standard resource type used in the optimization model. A capacity-based resource that carries working hours, a geographic position, and optional depot/load capacity configuration for pickup-and-delivery scenarios.", "allOf" : [ { "$ref" : "#/components/schemas/ResourceType" }, { "type" : "object", "properties" : { "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "Capacity", "default" : "Capacity" } } } ] }, "ConnectedConstraint" : { "required" : [ "connectionType", "constraintOne", "constraintTwo", "typeName" ], "type" : "object", "description" : "A compound constraint that logically connects two individual constraints via a ConnectionType (AND, OR). For example, a node may require 'skill A AND resource from zone 3', or 'either resource Jack OR resource Jane'.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "constraintOne" : { "$ref" : "#/components/schemas/Constraint" }, "constraintTwo" : { "$ref" : "#/components/schemas/Constraint" }, "connectionType" : { "type" : "string", "description" : "The logical operator connecting constraintOne and constraintTwo. Defines whether both must be satisfied (AND) or at least one (OR).", "enum" : [ "AND_CONNECTION_TYPE", "OR_CONNECTION_TYPE" ] }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "ConnectedConstraint", "default" : "ConnectedConstraint" } } } ] }, "ConnectionByTime" : { "required" : [ "distanceMeters", "timeDefinitions", "timeMillis" ], "type" : "object", "properties" : { "timeDefinitions" : { "type" : "array", "description" : "The timeDefinitions describe at which times, what connection should be used.", "items" : { "oneOf" : [ { "$ref" : "#/components/schemas/AnyDef" }, { "$ref" : "#/components/schemas/Day" }, { "$ref" : "#/components/schemas/DayMonth" }, { "$ref" : "#/components/schemas/DayMonthYear" }, { "$ref" : "#/components/schemas/RangeDay" }, { "$ref" : "#/components/schemas/RangeDayMonth" }, { "$ref" : "#/components/schemas/RangeDayMonthYear" }, { "$ref" : "#/components/schemas/RangeWeekDay" }, { "$ref" : "#/components/schemas/WeekDay" } ] } }, "timeMillis" : { "type" : "array", "description" : "The times to pass the connection in milliseconds for the underlying time defitions.", "items" : { "type" : "integer", "description" : "The times to pass the connection in milliseconds for the underlying time defitions.", "format" : "int64" } }, "distanceMeters" : { "type" : "array", "description" : "The length of the connection in meters.", "items" : { "type" : "number", "description" : "The length of the connection in meters.", "format" : "double" } } }, "description" : "The connectionByTime defines an extension to the connection. For example, on Monday morning we need 2 hours to path a connection, whereas on Sunday morning we only need 1 hour." }, "ConnectionRelatedLateMargin" : { "required" : [ "marginFactor", "maxMargin" ], "type" : "object", "properties" : { "shiftElementConnectionRealtedLateMargin" : { "type" : "boolean", "description" : "If true, the optimizer shifts the element's effective time window by the computed late margin, rather than simply absorbing the lateness as a soft violation. Produces a cleaner schedule representation." }, "applyPartialConnectionRelatedLateMargin" : { "type" : "boolean", "description" : "If true, partial late margins are applied proportionally based on the actual connection time relative to the maximum margin. If false, the full margin is applied as a binary threshold." }, "maxMargin" : { "type" : "string", "description" : "The maximum late-arrival margin that can be granted, regardless of how long the inbound connection is. Caps the proportional margin to prevent excessively permissive lateness tolerance.", "format" : "duration", "example" : "PT10M" }, "marginFactor" : { "type" : "number", "description" : "A factor between 0.0 and 1.0 that determines what proportion of the inbound connection time is granted as late-arrival margin. For example, a factor of 0.2 on a 50-minute connection yields a 10-minute margin (capped by maxMargin).", "format" : "double", "example" : 0.2 } }, "description" : "Configures a distance- or time-proportional late-arrival tolerance for a pillar node. If the inbound connection is long, the optimizer grants a proportional margin before counting lateness as a violation. Useful for fixed appointments where minor lateness is acceptable when traveling from distant locations." }, "Constraint" : { "required" : [ "isHard", "type" ], "type" : "object", "properties" : { "initialClassName" : { "type" : "string", "description" : "A constraint can transform during json serialization and deserialization. For example, the user changes the isHard property. To reflect this, on next loading via JSON the constraint is transformed. The initial class name helps to understand the origin of the constraint. to be fulfilled.", "nullable" : true }, "type" : { "$ref" : "#/components/schemas/ConstraintType" }, "isHard" : { "type" : "boolean", "description" : "Defines if a constraint is soft contrained or hard constraint. A hard constraint is fullfilled by the architectural design of the Optimzer. Therefore a hard constraint violation cannot occure. However, not all constraints can be hard-constraint-" } }, "description" : "The constraints of the Resource" }, "ConstraintType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "A node-level constraint that restricts which resources may visit a node, or penalizes undesirable assignments. Subtypes include binding/excluding resource constraints, type-based skill matching (with optional expertise levels and cost models), zone number and UK post code territory constraints, magneto (node-to-node attraction/repulsion) constraints, and multi-route node color constraints.", "discriminator" : { "propertyName" : "typeName", "mapping" : { "ConnectedConstraint" : "#/components/schemas/ConnectedConstraint", "BindingResource" : "#/components/schemas/BindingResourceConstraint", "ExcludingResource" : "#/components/schemas/ExcludingResourceConstraint", "ResourceLocationConstraint" : "#/components/schemas/ResourceLocationConstraint", "Type" : "#/components/schemas/TypeConstraint", "TypeWithExpertise" : "#/components/schemas/TypeWithExpertiseConstraint", "ZoneNumberConstraint" : "#/components/schemas/ZoneNumberConstraint", "UKPostCodeConstraint" : "#/components/schemas/UKPostCodeConstraint", "NodeColorMultiRouteConstraint" : "#/components/schemas/NodeColorMultiRouteConstraint", "AbsoluteNodeColorMultiRouteConstraint" : "#/components/schemas/AbsoluteNodeColorMultiRouteConstraint", "MagnetoNode" : "#/components/schemas/MagnetoNodeConstraint", "BitType" : "#/components/schemas/BitTypeConstraint", "BitTypeWithExpertise" : "#/components/schemas/BitTypeWithExpertiseConstraint" } } }, "ConstructionHook" : { "required" : [ "type" ], "type" : "object", "properties" : { "type" : { "$ref" : "#/components/schemas/HookType" } }, "description" : "The hooks for this working hour." }, "ConstructionOptimizationAlgorithmConfig" : { "required" : [ "algorithm" ], "type" : "object", "properties" : { "algorithm" : { "type" : "string", "description" : "The algorithm", "enum" : [ "SIMULTANEOUS_SPACE_SAVINGS_ALGO", "PICKY_SIMULTANEOUS_SPACE_SAVINGS_ALGO", "SEQUENTIAL_SPACE_SAVINGS_ALGO", "CLUSTERED_SEQUENTIAL_SPACE_SAVINGS_ALGO", "CLUSTERED_SEQUENTIAL_SPACE_SAVINGS_WITH_REASSIGNMENT_ALGO", "FULL_ASSIGNMENT_BASED_ALGO", "CLUSTERED_MULTI_LAYER_SEQUENTIAL_SPACE_SAVINGS_ALGO", "SMART_CONSTR_ALGO" ] } }, "description" : "The configuration for the construction algorithm phase. Defines which construction heuristic to use (e.g. nearest-neighbor, cheapest-insertion) and its parameters. This phase builds the initial solution before the heuristic improvement phases begin." }, "CoreBuildOptions" : { "required" : [ "buildCoreProperties" ], "type" : "object", "properties" : { "buildCoreProperties" : { "$ref" : "#/components/schemas/ImmutableMapStringString" } }, "description" : "Read-only metadata populated by the JOpt core library after an optimization run. Contains build properties such as the core library version, build timestamp, and Java runtime version. Useful for diagnostics, reproducibility audits, and support-ready bug reports. Do not set this field in the input — it is output-only." }, "CreatorSetting" : { "type" : "object", "properties" : { "creator" : { "type" : "string", "description" : "The creator" } }, "description" : "The creatorSetting" }, "DateDef" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "Polymorphic date predicate. Use the typeName property to select the concrete subtype. Point types (Day, DayMonth, DayMonthYear, WeekDay) match a single date. Range types (Range.Day, Range.DayMonth, Range.DayMonthYear, Range.WeekDay) match any date within a from–to interval. AnyDef combines multiple predicates with OR logic.", "discriminator" : { "propertyName" : "typeName", "mapping" : { "Any" : "#/components/schemas/AnyDef", "Day" : "#/components/schemas/Day", "DayMonth" : "#/components/schemas/DayMonth", "DayMonthYear" : "#/components/schemas/DayMonthYear", "WeekDay" : "#/components/schemas/WeekDay", "Range.Day" : "#/components/schemas/RangeDay", "Range.DayMonth" : "#/components/schemas/RangeDayMonth", "Range.DayMonthYear" : "#/components/schemas/RangeDayMonthYear", "Range.WeekDay" : "#/components/schemas/RangeWeekDay" } } }, "Day" : { "type" : "object", "description" : "Matches a specific day of the month (1–31).", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "day" : { "maximum" : 31, "minimum" : 1, "type" : "integer", "description" : "Day of the month.", "format" : "int32", "example" : 15 } } } ] }, "DayMonth" : { "type" : "object", "description" : "Matches a specific day within a specific month.", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "month" : { "maximum" : 12, "minimum" : 1, "type" : "integer", "description" : "Month of the year (1–12).", "format" : "int32", "example" : 4 }, "day" : { "maximum" : 31, "minimum" : 1, "type" : "integer", "description" : "Day of the month (1–31).", "format" : "int32", "example" : 15 } } } ] }, "DayMonthYear" : { "type" : "object", "description" : "Matches a specific date (year, month, day).", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "year" : { "type" : "integer", "description" : "Year.", "format" : "int32", "example" : 2026 }, "month" : { "maximum" : 12, "minimum" : 1, "type" : "integer", "description" : "Month of the year (1–12).", "format" : "int32", "example" : 4 }, "day" : { "maximum" : 31, "minimum" : 1, "type" : "integer", "description" : "Day of the month (1–31).", "format" : "int32", "example" : 15 } } } ] }, "DegradingLoadCapacity" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/ILoadCapacity" }, { "type" : "object", "properties" : { "loadCapacityId" : { "type" : "string" }, "maxCapacityValue" : { "type" : "integer", "description" : "The maximum individual load capacity of this depot entry.", "format" : "int32", "example" : 100 }, "capacityDegradationPerStop" : { "type" : "number", "format" : "double" }, "minimalTotaDegradatedCapacity" : { "type" : "number", "format" : "double" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "DegradingLoadCapacity", "default" : "DegradingLoadCapacity" } } } ] }, "DifferentVisitorNodeRelation" : { "required" : [ "typeName" ], "type" : "object", "description" : "A relation requiring that the master node and related nodes are visited by different resources. Ensures distinct resource assignments for the coupled nodes.", "allOf" : [ { "$ref" : "#/components/schemas/NodeRelationType" }, { "type" : "object", "properties" : { "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "DifferentVisitor", "default" : "DifferentVisitor" } } } ] }, "EdgeElementConnection" : { "required" : [ "distance", "typeName" ], "type" : "object", "description" : "An edge-based connection between two elements specifying travel distance, optional travel time, and optional time-dependent traffic profiles via connectionByTime. The standard connection type used to supply precomputed routing data to the optimizer.", "allOf" : [ { "$ref" : "#/components/schemas/ElementConnectionType" }, { "type" : "object", "properties" : { "distance" : { "type" : "string", "description" : "The distance of the connection.", "example" : "100.0 km" }, "time" : { "type" : "string", "description" : "The time needed to pass the connection.", "format" : "duration", "example" : "PT30M" }, "fromPosition" : { "$ref" : "#/components/schemas/Position" }, "toPosition" : { "$ref" : "#/components/schemas/Position" }, "connectionByTime" : { "$ref" : "#/components/schemas/ConnectionByTime" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "Edge", "default" : "Edge" } } } ] }, "ElementConnection" : { "required" : [ "fromElementId", "toElementId", "type" ], "type" : "object", "properties" : { "fromElementId" : { "type" : "string", "description" : "The fromElementId defines the element where the connections starts.", "example" : "MyStartElementId" }, "toElementId" : { "type" : "string", "description" : "The toElementId defines the element where the connections ends.", "example" : "MyToElementId" }, "type" : { "$ref" : "#/components/schemas/ElementConnectionType" } }, "description" : "Pre-computed pairwise connections between elements (nodes and resources). Each connection specifies the travel distance and time between a source and a target element, optionally including time-dependent traffic profiles via connectionByTime. If connections are not provided, the optimizer falls back to a Haversine-based distance approximation or a configured backup connector. Providing accurate connections significantly improves solution quality. In persisted results, this list may be omitted to conserve storage (controlled via saveConnections)." }, "ElementConnectionType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "A precomputed connection (distance and driving time) between two elements (nodes or resources). Used to supply custom or externally calculated travel data instead of relying on the optimizer's internal distance calculation. Currently supports edge-based connections.", "discriminator" : { "propertyName" : "typeName", "mapping" : { "Edge" : "#/components/schemas/EdgeElementConnection" } } }, "EncodedPolyline" : { "required" : [ "encodedPolyline", "precision" ], "type" : "object", "properties" : { "encodedPolyline" : { "type" : "string", "description" : "An encoded polyline (see e.g.: https://developers.google.com/maps/documentation/utilities/polylinealgorithm)." }, "precision" : { "type" : "number", "description" : "The precision of the encoded polyline.", "format" : "double" } }, "description" : "A Google-style encoded polyline string representing a geographic path between two elements. Includes a configurable precision value (default 1E5) for coordinate encoding/decoding." }, "EventNode" : { "required" : [ "typeName" ], "type" : "object", "description" : "A non-geographic node type representing a time-based task without a physical location (e.g. a phone call, virtual meeting, or administrative task). The optimizer schedules it based on time constraints only, with zero travel time and distance.", "allOf" : [ { "$ref" : "#/components/schemas/NodeType" }, { "type" : "object", "properties" : { "pillarNode" : { "$ref" : "#/components/schemas/PillarType" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "Event", "default" : "Event" }, "isPartialExchangeIdleForDrivingTime" : { "type" : "boolean", "description" : "An EventNode is allowed to be visited BEWTWEEN two Nodes and does not need to be positioned at a node.", "nullable" : true, "default" : true } } } ] }, "EventPillarNode" : { "required" : [ "typeName" ], "type" : "object", "description" : "A non-geographic pillar node representing a time-based task (e.g. a meeting, phone call, or administrative block) locked to a specific resource. Like GeoPillarNode but without spatial coordinates — the optimizer schedules it based on time constraints only.", "allOf" : [ { "$ref" : "#/components/schemas/PillarType" }, { "type" : "object", "properties" : { "attachedResourceId" : { "type" : "string", "description" : "The attached resourceId. An event pillar must be visited by this specific resource. The optimizer guarantees architectural compliance — this is a hard constraint." }, "onlyScheduledInCompany" : { "type" : "boolean", "description" : "If true, this event pillar is only scheduled when the attached resource belongs to the same organizational group. Prevents cross-company assignments in multi-fleet scenarios." }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "EventPillarNode", "default" : "EventPillarNode" }, "isOverwritingRouteTermination" : { "type" : "boolean", "description" : "The boolean isOverwritingRouteTermination. Instead of using the default termination element of the route, the geoPillar will be used as so-called endAnchor." }, "isSchedulableAfterWorkingHours" : { "type" : "boolean", "description" : "If true, the optimizer may schedule this event pillar after the resource's official working-hours end. Enables post-shift mandatory events (e.g. end-of-day reporting, handover calls)." }, "isSchedulableBeforeWorkingHours" : { "type" : "boolean", "description" : "If true, the optimizer may schedule this event pillar before the resource's official working-hours start. Enables pre-shift mandatory events (e.g. morning briefings, pre-route phone calls)." }, "isTimeAdjustableAnchor" : { "type" : "boolean", "description" : "If true, the anchor timing derived from this event pillar is allowed to shift within the working-hour boundaries. Enables the optimizer to adjust the schedule around fixed events while maintaining the pillar's role as a route anchor point." }, "isExtendableEnd" : { "type" : "boolean", "description" : "If true, the event pillar's end time can be extended beyond its defined opening-hour boundary to accommodate scheduling needs. Useful for flexible-duration events like meetings or calls." } } } ] }, "ExcludingResourceConstraint" : { "required" : [ "resources", "typeName" ], "type" : "object", "description" : "A node constraint that excludes specific resources from visiting this node. The listed resources will not be assigned to this node (hard) or will incur penalty cost if assigned (soft).", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "resources" : { "type" : "array", "description" : "The list of resources that should NOT visit a certain node.", "items" : { "$ref" : "#/components/schemas/ResourceWithPriority" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "ExcludingResource", "default" : "ExcludingResource" } } } ] }, "GeoAddress" : { "type" : "object", "properties" : { "locationId" : { "type" : "string", "description" : "An optional identifier linking this address to a shared location entry.", "example" : "MyLocationId" }, "housenumber" : { "type" : "string", "description" : "The house number of the address.", "example" : "5" }, "streetname" : { "type" : "string", "description" : "The street name of the address (without house number).", "example" : "Marlene-Dietrich-Strasse" }, "city" : { "type" : "string", "description" : "The city or locality name.", "example" : "Neu-Ulm" }, "county" : { "type" : "string", "description" : "The county or administrative district." }, "state" : { "type" : "string", "description" : "The state or region name." }, "statecode" : { "type" : "string", "description" : "The state or region code (abbreviated form, e.g. 'NSW', 'BY')." }, "country" : { "type" : "string", "description" : "The country name (e.g. 'Germany', 'Australia').", "example" : "Germany" }, "macrocountry" : { "type" : "string", "description" : "The macro-country or metropolitan region (e.g. 'Berlin', 'Sydney').", "example" : "Berlin" }, "countrycode" : { "type" : "string", "description" : "The country code (ISO CODE)", "example" : "DE" }, "postalcode" : { "type" : "string", "description" : "The postal or ZIP code.", "example" : "89231" }, "layer" : { "type" : "string", "description" : "The geocoding layer (e.g. 'address', 'venue', 'street') indicating the granularity of the match." }, "source" : { "type" : "string", "description" : "The geocoding data source (e.g. 'openstreetmap', 'geonames') that provided this address." }, "accuracy" : { "type" : "string", "description" : "The accuracy level of the geocoding result (e.g. 'point', 'centroid', 'interpolated')." }, "confidence" : { "type" : "number", "description" : "This is a general score computed to calculate how likely result is what was asked for. It's meant to be a combination of all the information available to Pelias. It's not super sophisticated, and results may not be sorted in confidence-score order. In that case results returned first should be trusted more. Confidence scores are floating point numbers ranging from '0.0' to '1.0'.", "format" : "double", "example" : 1.0 }, "label" : { "type" : "string", "description" : "A fully formatted address label combining all available components (e.g. '495 Old South Head Road, Rose Bay, NSW, Australia')." } }, "description" : "A structured geographic address used for geocoding. Contains fields for street, house number, postal code, city, country, region, and other GeoJSON-compatible address components. When provided on a Position, the geocoder resolves it to latitude/longitude coordinates." }, "GeoNode" : { "required" : [ "position", "typeName" ], "type" : "object", "description" : "A geographic node type with a physical position (latitude/longitude). Represents a customer location, delivery point, or field-service site that a resource must physically travel to.", "allOf" : [ { "$ref" : "#/components/schemas/NodeType" }, { "type" : "object", "properties" : { "position" : { "$ref" : "#/components/schemas/Position" }, "pillarNode" : { "$ref" : "#/components/schemas/PillarType" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "Geo", "default" : "Geo" } } } ] }, "GeoPillarNode" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/PillarType" }, { "type" : "object", "properties" : { "attachedResourceId" : { "type" : "string", "description" : "The attached resourceId. A geoPillar must be visited by this resource." }, "onlyScheduledInCompany" : { "type" : "boolean", "description" : "If true, this pillar node is only scheduled when the attached resource is part of the same organizational company/group. Prevents cross-company pillar assignments in multi-fleet scenarios." }, "connectionRelatedLateMargin" : { "$ref" : "#/components/schemas/ConnectionRelatedLateMargin" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "GeoPillarNode", "default" : "GeoPillarNode" }, "isAutoTransformable2StartAnchor" : { "type" : "boolean", "description" : "If true, the optimizer may automatically promote this pillar to a route-start anchor when it determines that doing so improves the overall solution quality. Allows flexible anchor assignment without manual configuration." }, "isOverwritingRouteStart" : { "type" : "boolean", "description" : "The boolean isOverwritingRouteStart. Instead of using the default start element of the route, the geoPillar will be used as so-called startAnchor." }, "isOverwritingRouteTermination" : { "type" : "boolean", "description" : "The boolean isOverwritingRouteTermination. Instead of using the default termination element of the route, the geoPillar will be used as so-called endAnchor." }, "isSchedulableAfterWorkingHours" : { "type" : "boolean", "description" : "If true, the optimizer is allowed to schedule this pillar node after the resource's official working-hours end. Useful for mandatory end-of-day stops (e.g. vehicle return, paperwork drop-off)." }, "isSchedulableBeforeWorkingHours" : { "type" : "boolean", "description" : "If true, the optimizer is allowed to schedule this pillar node before the resource's official working-hours start. Useful for mandatory stops (e.g. depot loading) that must happen pre-shift." }, "isTimeAdjustableAnchor" : { "type" : "boolean", "description" : "If true, the anchor timing derived from this pillar is allowed to shift within the working-hour boundaries. Enables the optimizer to adjust the schedule around fixed appointments while maintaining the pillar's role as a route start or termination anchor." }, "isForcedStayNode" : { "type" : "boolean", "description" : "If true, the optimizer must treat this pillar node as an overnight-stay location. The route will terminate here and the next working-hour route will start from this position." } } } ] }, "HeuristicOptimizationAlgorithmConfig" : { "required" : [ "algorithm" ], "type" : "object", "properties" : { "algorithm" : { "type" : "string", "description" : "The algorithm", "enum" : [ "SIMULATED_ANNEALING_ALGO", "PARALLEL_SIMULATED_ANNEALING_ALGO", "SMART_SIMULATED_ANNEALING_ALGO", "GENETIC_EVOLUTION_ALGO" ] }, "simulatedAnnealingOverrideNumIterationsValue" : { "type" : "integer", "description" : "The simulatedAnnealingOverrideNumIterationsValue", "format" : "int32" }, "hasAutoFilter" : { "type" : "boolean", "description" : "The hasAutoFilter" } }, "description" : "An ordered list of heuristic algorithm configurations that are executed sequentially after construction. Each entry defines an algorithm (e.g. Genetic Algorithm, Simulated Annealing) and its parameters (iteration count, repetitions). The optimizer runs each phase in order to progressively improve the solution." }, "HookType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "The HookType that can contain different Hooks", "discriminator" : { "propertyName" : "typeName", "mapping" : { "MaxDistanceConstructionHook" : "#/components/schemas/d" } } }, "ILoad" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "loadValue" : { "type" : "number", "format" : "double" }, "fuzzyVisit" : { "type" : "boolean" }, "request" : { "type" : "boolean" }, "priority" : { "type" : "integer", "format" : "int32" }, "id" : { "type" : "string" }, "typeName" : { "type" : "string" } }, "description" : "A load attached to a node depot that represents goods to be picked up (supply) or delivered (request). Subtypes include simple loads, unload-all loads, timed loads (with maximum transport duration), and flexible loads (mixed, supply-only, or request-only flex loads that adjust dynamically during optimization).", "discriminator" : { "propertyName" : "typeName", "mapping" : { "SimpleLoad" : "#/components/schemas/SimpleLoad", "UnloadAllLoad" : "#/components/schemas/UnloadAllLoad", "MixedFlexLoad" : "#/components/schemas/MixedFlexLoad", "SupplyFlexLoad" : "#/components/schemas/SupplyFlexLoad", "RequestFlexLoad" : "#/components/schemas/RequestFlexLoad" } } }, "ILoadCapacity" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "currentLoad" : { "type" : "number", "format" : "double" }, "loadPickupTime" : { "type" : "integer", "format" : "int64" }, "maximalIndividualLoadCapacity" : { "type" : "number", "format" : "double" }, "id" : { "type" : "string" }, "typeName" : { "type" : "string" } }, "description" : "The LoadCapacity type", "discriminator" : { "propertyName" : "typeName", "mapping" : { "SimpleLoadCapacity" : "#/components/schemas/SimpleLoadCapacity", "DegradingLoadCapacity" : "#/components/schemas/DegradingLoadCapacity" } } }, "INodeDepot" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "depotId" : { "type" : "string" }, "items" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ILoad" } }, "typeName" : { "type" : "string" } }, "description" : "The NodeDepot type", "discriminator" : { "propertyName" : "typeName", "mapping" : { "SimpleNodeDepot" : "#/components/schemas/SimpleNodeDepot" } } }, "IResourceDepot" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "maximalTotalCapacity" : { "type" : "number", "format" : "double" }, "capacityUnitMap" : { "type" : "object", "additionalProperties" : { "type" : "number", "format" : "double" } }, "depotId" : { "type" : "string" }, "items" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ILoadCapacity" } }, "typeName" : { "type" : "string" } }, "description" : "A resource-level depot that defines the initial goods/capacity a resource carries at route start. Holds a collection of load capacities and manages load exchange when visiting node depots during pickup-and-delivery scenarios.", "discriminator" : { "propertyName" : "typeName", "mapping" : { "SimpleResourceDepot" : "#/components/schemas/SimpleResourceDepot" } } }, "IdleEventNode" : { "required" : [ "typeName" ], "type" : "object", "description" : "A system-generated non-geographical node that represents idle time or a synthetic event inserted by the optimizer during construction or heuristic phases. This node type is never created by the user — it is produced internally to model waiting periods, return-to-start segments, or inter-route padding.", "allOf" : [ { "$ref" : "#/components/schemas/NodeType" }, { "type" : "object", "properties" : { "pillarNode" : { "$ref" : "#/components/schemas/PillarType" }, "masterId" : { "type" : "string", "description" : "The id of the master node that triggered the creation of this idle event (e.g. in relation-based or return-to-start scenarios)." }, "relatedId" : { "type" : "string", "description" : "The id of the related node associated with this idle event (e.g. the node the resource is waiting for)." }, "creationTimeStamp" : { "type" : "integer", "description" : "The epoch-millisecond timestamp when this idle event node was created by the optimizer.", "format" : "int64" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "IdleEvent", "default" : "IdleEvent" } } } ] }, "ImmutableMapStringString" : { "type" : "object", "additionalProperties" : { "type" : "string", "description" : "The properties of the Optimization run. For example, the number of iterations for the Optimization run or the weight for certain Optimization goals can be defined." }, "description" : "The properties of the Optimization run. For example, the number of iterations for the Optimization run or the weight for certain Optimization goals can be defined." }, "IntegerMultiConstraintHelperItem" : { "required" : [ "pairs" ], "type" : "object", "properties" : { "pairs" : { "type" : "array", "description" : "A list of key-value pairs mapping element identifiers to integer values. Used internally to mirror multi-route constraint configurations across working hours.", "items" : { "$ref" : "#/components/schemas/StringIntegerPair" } } }, "description" : "The mirroring configuration that maps this constraint across working-hour boundaries." }, "JSONConfig" : { "type" : "object", "properties" : { "creatorSetting" : { "$ref" : "#/components/schemas/CreatorSetting" }, "textSolution" : { "$ref" : "#/components/schemas/TextSolution" }, "keySetting" : { "$ref" : "#/components/schemas/OptimizationKeySetting" }, "persistenceSetting" : { "$ref" : "#/components/schemas/OptimizationPersistenceSetting" }, "pluginSettings" : { "$ref" : "#/components/schemas/PluginSettings" }, "timeOut" : { "type" : "string", "description" : "The timeout for the optimization run.", "format" : "duration", "example" : "PT2H" } }, "description" : "A generic extension object that carries environment-specific configuration outside the core optimization model. In the REST/Docker variant (where EXT = JSONConfig), this typically includes: the license key setting (keySetting), persistence settings for Fire-and-Forget mode (persistenceSetting with MongoDB configuration, encryption secrets, stream persistence strategies, and TTL expiry), a creator setting for tenant identification, and a timeout duration. The extension is stripped of sensitive fields (e.g. keySetting) before the result is persisted to the database." }, "JsonNode" : { "type" : "object", "description" : "The raw json descirbing the trip." }, "LoadDimension" : { "required" : [ "totalLoadDimension", "unloadAllDimension" ], "type" : "object", "properties" : { "unloadAllDimension" : { "type" : "integer", "description" : "The number of load dimensions that participate in the unload-all operation. For example, if the resource carries goods across 3 dimensions (weight, volume, pallets) and unloadAllDimension is set to 2, only the first 2 dimensions are emptied at this node.", "format" : "int32" }, "totalLoadDimension" : { "type" : "integer", "description" : "The total number of load dimensions defined for this node. Must match the dimensionality of the resource's capacity vector and the node's load vector.", "format" : "int32" }, "unloadAll" : { "type" : "boolean", "description" : "If true, the resource unloads all remaining cargo at this node before continuing. Typically used at depot-return nodes or redistribution hubs in PND scenarios." } }, "description" : "The load dimension descriptor for pickup-and-delivery (PND) scenarios. Defines how loads are interpreted at this node — for example, whether goods are picked up from or delivered to this location, and how the load interacts with the resource's capacity vector." }, "LocationParameters" : { "type" : "object", "properties" : { "layers" : { "type" : "string", "description" : "The layers in which the location can be detected. Use 'auto' for automatically selecting the best (highest confidence) layer.", "example" : "address" }, "size" : { "type" : "integer", "description" : "The number of layers the location can be related to. Further, in case of a query the number of results that might be found/desired.", "format" : "int32", "example" : 1 }, "radius" : { "type" : "number", "description" : "The number of meters about this input location within which edges (roads between intersections) will be considered as candidates for said location. When correlating this location to the route network, try to only return results within this distance (meters) from this location. If there are no candidates within this distance it will return the closest candidate within reason. If this value is larger than the configured service limit it will be clamped to that limit. The default is 20 meters.", "format" : "double", "example" : 20 }, "sources" : { "type" : "string", "description" : "If you use the sources parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding an address in data from OpenAddresses, for example, you can build a query specifying that data source 'oa'. (OpenAddresses='oa', OpenstreetMap = 'osm', Who's on First ='wof',GeoNames='gn' ). If, for example, OpenAddresses and OpenstreetMap is desired use 'osm,oa'. Default is 'all' ", "example" : "all" } }, "description" : "Location parameters that can support geographical routing." }, "LongLongPair" : { "required" : [ "left", "right" ], "type" : "object", "properties" : { "left" : { "type" : "integer", "description" : "The start offset value (in milliseconds).", "format" : "int64" }, "right" : { "type" : "integer", "description" : "The end offset value (in milliseconds).", "format" : "int64" } }, "description" : "Optional offset pairs that define sub-windows within this opening hour during which the node can actually be serviced. Each pair specifies a start offset and an end offset (in milliseconds) relative to the opening-hour begin. Useful for modeling lunch breaks, shift handovers, or restricted access periods within an otherwise open time window." }, "MagnetoNodeConstraint" : { "required" : [ "isAttractingMagnet", "nodeMagnetIds", "order", "typeName" ], "type" : "object", "description" : "A node-to-node soft constraint that creates magnetic attraction or repulsion between nodes. In attraction mode, the optimizer prefers placing the listed nodes on the same route. In repulsion mode, it prefers separating them. Supports ordering preferences (front/back of route).", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "nodeMagnetIds" : { "type" : "array", "description" : "A list of user-provided node-magntet-ids. Attraction Mode: A node holding this constraints attracts nodes (defined via ids) to share the same route. Repulsive mode: A node holding this constraints repels nodes (defined via ids).", "items" : { "type" : "string", "description" : "A list of user-provided node-magntet-ids. Attraction Mode: A node holding this constraints attracts nodes (defined via ids) to share the same route. Repulsive mode: A node holding this constraints repels nodes (defined via ids)." } }, "order" : { "type" : "string", "description" : "The desired order. For example, if desired node order is front, the node carrying the constraint is ideally in front of the other nodes defined in nodeMagnetIds.", "enum" : [ "NO_ORDER", "FRONT", "BACK" ] }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "MagnetoNode", "default" : "MagnetoNode" }, "isAttractingMagnet" : { "type" : "boolean", "description" : "True: Attracting nodes. False: Repel nodes." } } } ] }, "MixedFlexLoad" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/ILoad" }, { "type" : "object", "properties" : { "loadId" : { "type" : "string" }, "isRequest" : { "type" : "boolean" }, "isFuzzyVisit" : { "type" : "boolean" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "MixedFlexLoad", "default" : "MixedFlexLoad" } } } ] }, "MongoOptimizationPersistenceSetting" : { "required" : [ "enablePersistence", "optimizationPersistenceStrategySetting", "requireUniqueIdentCreatorCombination", "secret", "streamPersistenceStrategySetting" ], "type" : "object", "properties" : { "enablePersistence" : { "type" : "boolean", "description" : "The enablePersistence" }, "requireUniqueIdentCreatorCombination" : { "type" : "boolean", "description" : "The requireUniqueIdentCreatorCombination" }, "secret" : { "type" : "string", "description" : "The secret that encrypts the result. If empty, no encryption is assigned. Important: Metadata and stream information like progress is always saved as decrypted clear text. Attention: The secret is not saved by DNA evolutions. If you loose the secret, the file CAN NOT be restored." }, "expiry" : { "type" : "string", "description" : "The document will be automatically deleted after this duration. The default value is 48 hours.", "format" : "duration", "example" : "PT48H" }, "optimizationPersistenceStrategySetting" : { "$ref" : "#/components/schemas/OptimizationPersistenceStrategySetting" }, "streamPersistenceStrategySetting" : { "$ref" : "#/components/schemas/StreamPersistenceStrategySetting" }, "completionWebhookUrl" : { "type" : "string", "description" : "Optional URL the server calls (POST) when the job completes or fails. The payload contains jobId, tenantId, status, and completedAt only — no optimization data. Leave empty to disable. URL validation is controlled by the server's webhook-validation policy: in strict mode (SaaS default) only public HTTPS URLs are accepted; in relaxed mode (on-premise) HTTP and private network addresses are also allowed; in none mode (local development) any URL is accepted. Loopback addresses (127.x, ::1) are always rejected. Validation is performed at submission time." }, "completionWebhookSecret" : { "type" : "string", "description" : "Optional secret used to sign the webhook payload with HMAC-SHA256. When provided, the server includes an X-JOpt-Signature header on every delivery in the form 'sha256='. The receiver should compute the same HMAC over the raw request body and compare it using a constant-time comparison before trusting the payload. Leave empty to send unsigned webhooks. Unsigned webhooks are acceptable in trusted internal networks but are not recommended when the webhook URL is reachable from untrusted clients." } }, "description" : "The mongoSettings" }, "MultiTimeWindowNodeRelation" : { "required" : [ "isNeedSameVisitor", "isOverlapAllowed", "typeName" ], "type" : "object", "description" : "An advanced relation type that supports multiple time-window constraints between a master node and related nodes. Optionally requires the same visitor for all elements and can allow temporal overlaps between visits. Supports anchor details for biasing the relation scheduling.", "allOf" : [ { "$ref" : "#/components/schemas/NodeRelationType" }, { "type" : "object", "properties" : { "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "MultiTimeWindow", "default" : "MultiTimeWindow" }, "anchorDetails" : { "type" : "array", "description" : "The anchorDetails. The list of anchorDetails biasing the relation.", "items" : { "$ref" : "#/components/schemas/RouteElementDetail" } }, "isNeedSameVisitor" : { "type" : "boolean", "description" : "Do we want the same visitor for all elements of the relation?" }, "isOverlapAllowed" : { "type" : "boolean", "description" : "Do we want to allow overlaps - makes sense if isNeedSameVisitor is false?" } } } ] }, "Node" : { "required" : [ "id", "openingHours", "type", "visitDuration" ], "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "The unique id of the node. It is not possible, to create mutliple elements (also Resources) with the same id.", "example" : "MySecondNode" }, "extraInfo" : { "type" : "string", "description" : "A custom extra info string that is attached to the Node.", "example" : "My custom extra info" }, "locationId" : { "type" : "string", "description" : "The location id can relate a node to the connection of another node. For example the node 'MyFirstNode' and 'MySecondNode' have the same location. It is sufficient to provide the connection data for 'MyFirstNode' and set the LocationId of 'MySecondNode' to be 'MyFirstNode'", "example" : "MyFirstNode" }, "constraintAliasId" : { "type" : "string", "description" : "The constraintAliasId. If set is used during constraint assessment instead of using the normal id.", "example" : "MyNodeXXX" }, "type" : { "$ref" : "#/components/schemas/NodeType" }, "openingHours" : { "type" : "array", "description" : "The list of non-overlapping openingHours of the nodes.", "items" : { "$ref" : "#/components/schemas/OpeningHours" } }, "visitDuration" : { "type" : "string", "description" : "The visitDuration defines how long a visitor needs to stay at the node.", "format" : "duration", "example" : "PT60M" }, "constraints" : { "type" : "array", "description" : "The constraints of this node", "items" : { "$ref" : "#/components/schemas/Constraint" } }, "offeredNode" : { "$ref" : "#/components/schemas/OfferedNode" }, "loadDimension" : { "$ref" : "#/components/schemas/LoadDimension" }, "load" : { "type" : "array", "description" : "The multi-dimensional load vector for this node in pickup-and-delivery scenarios. Each element corresponds to a capacity dimension on the resource (e.g. weight, volume, pallet count). Positive values typically represent demand (delivery), while the interpretation depends on the loadDimension configuration.", "items" : { "type" : "number", "description" : "The multi-dimensional load vector for this node in pickup-and-delivery scenarios. Each element corresponds to a capacity dimension on the resource (e.g. weight, volume, pallet count). Positive values typically represent demand (delivery), while the interpretation depends on the loadDimension configuration.", "format" : "double" } }, "qualifications" : { "type" : "array", "description" : "The qualifications of the node.", "items" : { "$ref" : "#/components/schemas/Qualification" } }, "lockdownTime" : { "type" : "integer", "description" : "An optional lockdown time (in milliseconds) during which this node cannot be reassigned or moved by the optimizer after initial placement. Useful for protecting confirmed appointments from being rescheduled during re-optimization runs.", "format" : "int64" }, "fixCost" : { "type" : "number", "description" : "The fixCost defines an abstract cost that arrises when this node is visited.", "format" : "double" }, "priority" : { "type" : "integer", "description" : "The priority of the node. A higher priority leads to a higher cost if a node shows violations. As the Optimizer tries to reduce cost, a higher priority results in lower chance of seeing violations on this node. However, if all nodes of an Optimization have a priority, the effect vanishes.", "format" : "int32" }, "priorityFirst" : { "type" : "integer", "description" : "The priorityFirst defines if we want a node to be the first node in a route-solution.", "format" : "int32" }, "priorityLast" : { "type" : "integer", "description" : "The priorityLast defines if we want a node to be the last node in a route-solution.", "format" : "int32" }, "nodeColor" : { "$ref" : "#/components/schemas/NodeColor" }, "minAutoFilterProtectedExecutions" : { "type" : "integer", "description" : "The minimum number of optimization executions during which this node is protected from being removed by the AutoFilter. After this many executions, the AutoFilter may exclude this node if it consistently causes infeasibility. Set to 0 (default) to allow immediate filtering.", "format" : "int32" }, "nodeDepot" : { "$ref" : "#/components/schemas/INodeDepot" }, "routeDependentVisitDuration" : { "type" : "boolean", "description" : "If true, the actual visit duration at this node may be adjusted based on the resource's visitDurationEfficiency factor. A more efficient resource completes the task faster (down to minVisitDuration). If false, the visitDuration is fixed regardless of which resource visits.", "nullable" : true, "default" : false }, "allowMoveToReduceFlexTime" : { "type" : "boolean", "description" : "If true, the optimizer is allowed to reposition this node within the route sequence specifically to reduce the resource's flex-time usage. Useful when minimizing flex-time consumption is a priority (e.g. contractual constraints on early/late start deviations).", "nullable" : true, "default" : false }, "minVisitDuration" : { "type" : "string", "description" : "The minimum visit duration floor when routeDependentVisitDuration is enabled. Even if the resource's efficiency factor would reduce the visit time further, it cannot go below this threshold. Ensures a realistic minimum service time regardless of resource skill level.", "format" : "duration", "example" : "PT10M" }, "jointVisitDuration" : { "type" : "string", "description" : "The jointVisitDuration. If nodes are situated closely to each other (defined via property 'JOpt.JointVisitDuration.maxRadiusMeter') a joint visit duration can be defined. For example, 3 nodes have a visit duration of 20 minutes each. The joint visit duration for ALL nodes is set to be 10 minutes. Further, they are close enough to each other, that the joint visit duration logic can be triggered. The optimizer finds a solution in which all three nodes are visted in direct succession. The first node (of the three) needs to be visted for the original visit duration of 20 minutes. The seconds and third nodes only needs to be visited for 10 minutes.", "format" : "duration", "example" : "PT60M" }, "returnStartDuration" : { "type" : "string", "description" : "The duration the resource must spend at this node before returning to the route start location (return-to-start behavior). Used in scenarios where a resource must revisit its depot mid-route (e.g. to reload supplies) and the node acts as a return-to-start trigger point.", "format" : "duration" }, "isUnassigned" : { "type" : "boolean", "description" : "The boolean isUnassigned. Defines if a node was unassigned by the Optimizer.", "nullable" : true, "default" : false }, "isCausingIdleTimeCost" : { "type" : "boolean", "description" : "The boolean isCausingIdleTimeCost. By default, waiting at a node to open is creating idle time cost. As the Optimizer tries to reduce cost, it will also try to reschedule nodes if idle time cost is generated. In some problem setups (especially problems of the kind: Low node count, high WorkingHours availability) it may be desired to keep the position of the nodes, even though idle time is created.", "nullable" : true, "default" : true }, "isIgnoreOnZeroDuration" : { "type" : "boolean", "description" : "If true, this node is excluded from routing whenever its visit duration is zero. A node with zero visit duration contributes no service time to a route, so visiting it provides no operational value. Enabling this flag allows the optimizer to skip such nodes automatically, reducing route length and travel cost. Defaults to false.", "nullable" : true, "default" : false }, "isOpeningHoursIncludesDuration" : { "type" : "boolean", "description" : "The boolean isOpeningHoursIncludesDuration. By default a node's openingHour defines the time-window in which a task has to be fulfilled, meaning a Visitor has to arrive, work, and leave within that time-window. If isOpeningHoursIncludesDuration is set to false, the time-window only counts as arrival-window for the Resource.", "nullable" : true, "default" : true }, "isUnlocatedHubConnectionTime" : { "type" : "boolean", "description" : "False: If a resource in hub mode deals with this node, the earlist openingHours start of the node describes the earlist time the resource can start working on the node. TRUE: If a resource in hub mode deals with this node, the connection time is added to the earlist openinghour start of the node, effectively acting as offset. This can be used for example, for shipping scnearios where a package takes 3 days.", "nullable" : true, "default" : false }, "isWaitOnEarlyArrival" : { "type" : "boolean", "description" : "The boolean isWaitOnEarlyArrival. In case a Resources reaches a node too early (before the start of the node's OpeningHours), the Resource can either start working direclty (false) or wait for the node to open (true, default).", "nullable" : true, "default" : true }, "isWaitOnEarlyArrivalFirstNode" : { "type" : "boolean", "description" : "The boolean isWaitOnEarlyArrivalFirstNode. In case a Resources reaches the FIRST node of a route too early (before the start of the node's OpeningHours),\"\r\n + \" the Resource can either start working direclty (true) or wait for the FIRST node to open (false, default). This setting only takes action if isWaitOnEarlyArrival is set to true.", "nullable" : true, "default" : false }, "isIgnoreOnZeroLoad" : { "type" : "boolean", "description" : "If true, this node is excluded from routing whenever its effective load exchange is zero at the time of evaluation. For supply nodes this means the node is skipped once its available supply has been fully consumed. For request nodes (including coupled split-nodes) this means the node is suppressed when the optimizer has assigned zero demand to it - for example, when a coupled partner already carries the full group total. Setting this flag reduces unnecessary route stops and lowers travel cost without affecting the coupling invariant, since a zero-load node contributes nothing to the delivery. Defaults to false.", "nullable" : true, "default" : false }, "isStayNode" : { "type" : "boolean", "description" : "The boolean isStayNode defines if a node is capable to be a stay node. A stay node overrides the route termination element of a route, and the route start element of the next route and is used in the context of 'overnight-stays'.", "nullable" : true, "default" : false }, "isWorkNode" : { "type" : "boolean", "description" : "DEPRECATED. Defines whether this node represents actual productive work. When false, the node is treated as a non-productive stop (e.g. a waypoint or break location). This field is deprecated and may be removed in a future version.", "nullable" : true, "default" : true }, "isOptional" : { "type" : "boolean", "description" : "The boolean isOptional. If a node is optional, the Optimizer can decide on its own, if the node is visited or not. Usually, this settings only makes sense in PND problems.", "nullable" : true, "default" : false }, "isOptimizable" : { "type" : "boolean", "description" : "The boolean isOptimizable. Defines if a node is optimizable. This property will be auto-defined by the optimizer..", "nullable" : true, "default" : true } }, "description" : "A work item, customer location, or event to be scheduled and assigned to a resource. Each node defines a type (GeoNode, EventNode, or pillar variants), opening-hour windows, a required visit duration, and optional constraints, pickup-and-delivery loads, priority, node color, and relations to other nodes." }, "NodeColor" : { "required" : [ "colorCode", "colorId" ], "type" : "object", "properties" : { "colorCode" : { "type" : "integer", "description" : "A numeric color code identifying this color category. Must match the codes used in NodeColorCapacity constraints.", "format" : "int32" }, "colorId" : { "type" : "string", "description" : "A human-readable identifier for this color category (e.g. 'HAZARDOUS', 'PRIORITY_A', 'COLD_CHAIN')." }, "countValue" : { "type" : "integer", "description" : "The contribution count of this node towards its color category. Defaults to 1. A higher value means this node 'consumes' more of the route's color capacity budget.", "format" : "int32" } }, "description" : "The color category assigned to this node. Used in conjunction with NodeColorCapacity or AbsoluteNodeColorCapacity constraints on the resource's working hours to control route composition (e.g. limit the number of hazardous-goods stops per route). Defaults to the system DEFAULT color." }, "NodeColorCapacity" : { "required" : [ "maxUsage", "nodeColor" ], "type" : "object", "properties" : { "nodeColor" : { "$ref" : "#/components/schemas/NodeColor" }, "maxUsage" : { "type" : "number", "description" : "The maximum usage ratio (0.0–1.0) of this node color within a single route. For example, 0.5 means at most 50% of the nodes on a route may carry this color.", "format" : "double" } }, "description" : "Per-color capacity limits for routes produced from this working hour. Controls the composition of the route by limiting how many nodes of a given color category may appear (e.g. at most 40% hazardous-goods stops). Overrides any resource-level color capacity when set at the working-hour level." }, "NodeColorMultiRouteConstraint" : { "required" : [ "mirrorItem", "nodeColorCapacities", "typeName" ], "type" : "object", "description" : "A multi-route constraint that enforces per-color capacity limits across multiple working hours of a resource, using fractional (ratio-based) limits.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "mirrorItem" : { "$ref" : "#/components/schemas/IntegerMultiConstraintHelperItem" }, "nodeColorCapacities" : { "type" : "array", "description" : "The per-color capacity limits (ratio-based) enforced by this multi-route constraint.", "items" : { "$ref" : "#/components/schemas/NodeColorCapacity" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "NodeColorMultiRouteConstraint", "default" : "NodeColorMultiRouteConstraint" } } } ] }, "NodeRelation" : { "required" : [ "masterNodeId", "relatedNodeIds", "type" ], "type" : "object", "properties" : { "masterNodeId" : { "type" : "string", "description" : "The id of the master node in this relation. The master node serves as the anchor point — constraints are evaluated relative to this node's scheduling (e.g. 'master must be visited before related')." }, "relatedNodeIds" : { "type" : "array", "description" : "The list of related node ids that are coupled to the master node via this relation. All listed nodes must satisfy the relation type (e.g. all must be on the same route as the master).", "items" : { "type" : "string", "description" : "The list of related node ids that are coupled to the master node via this relation. All listed nodes must satisfy the relation type (e.g. all must be on the same route as the master)." } }, "type" : { "$ref" : "#/components/schemas/NodeRelationType" }, "relationMode" : { "type" : "string", "description" : "The enforcement mode of this relation. STRONG (default) means the optimizer always respects it. WEAK allows the optimizer to violate the relation at a cost if no feasible solution can satisfy it.", "enum" : [ "STRONG", "WEAK", "WEAK_TO_MATER", "WEAK_TO_RELATED" ] } }, "description" : "The list of inter-node relations that impose ordering or co-assignment constraints between nodes. Supported relation types include SAME_ROUTE (nodes must be on the same route), SAME_VISITOR (nodes must be served by the same resource), DIFFERENT_ROUTE (nodes must not share a route), and relative time-window relations that enforce temporal precedence (e.g. node A must be visited before node B within a defined time gap)." }, "NodeRelationType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "A relation that couples two or more nodes across time or resource assignment. Subtypes include time window relations (enforcing relative visit ordering with optional time gaps), same-visitor relations (requiring the same resource visits both nodes), different-visitor relations (requiring distinct resources), and multi-time-window relations.", "discriminator" : { "propertyName" : "typeName", "mapping" : { "TimeWindow" : "#/components/schemas/TimeWindowNodeRelation", "DifferentVisitor" : "#/components/schemas/DifferentVisitorNodeRelation", "SameVisitor" : "#/components/schemas/SameVisitorNodeRelation", "MultiTimeWindow" : "#/components/schemas/MultiTimeWindowNodeRelation" } } }, "NodeType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "The Nodetype that can contain different Nodes", "discriminator" : { "propertyName" : "typeName", "mapping" : { "Geo" : "#/components/schemas/GeoNode", "Event" : "#/components/schemas/EventNode", "IdleEvent" : "#/components/schemas/IdleEventNode" } } }, "OfferedNode" : { "type" : "object", "properties" : { "individualMultiplier" : { "type" : "number", "description" : "The cost multiplier for an offered node. If the multiplier is bigger than 1.0 the chances that the node shows violations is getting less.", "format" : "double" } }, "description" : "Marks a node as 'offered' — a high-priority node that the optimizer should try harder to schedule without violations. The individualMultiplier increases the cost penalty for violations on this node, making the optimizer prioritize it over regular nodes." }, "OpeningHours" : { "required" : [ "begin", "end", "zoneId" ], "type" : "object", "properties" : { "begin" : { "type" : "string", "description" : "The begin of the Opening Hour", "format" : "date-time", "example" : "2020-03-06T06:00:00Z" }, "end" : { "type" : "string", "description" : "The end of the Opening Hour", "format" : "date-time", "example" : "2020-03-06T19:00:00Z" }, "zoneId" : { "type" : "string", "description" : "The zoneId of the Opening Hour", "example" : "UTC" }, "serviceHoursOffsets" : { "type" : "array", "description" : "Optional offset pairs that define sub-windows within this opening hour during which the node can actually be serviced. Each pair specifies a start offset and an end offset (in milliseconds) relative to the opening-hour begin. Useful for modeling lunch breaks, shift handovers, or restricted access periods within an otherwise open time window.", "items" : { "$ref" : "#/components/schemas/LongLongPair" } }, "isPreffered" : { "type" : "boolean", "description" : "The isPreffered boolean. If an Opening Hour is preffered the Optimizer will try to visit the node inside this Opening Hour. By default, the first Openinghour of a node is the preffered opening hour.", "nullable" : true, "example" : false, "default" : false }, "isSoloAccessHours" : { "type" : "boolean", "description" : "If true, this opening hour grants exclusive access — the node can only be visited during this specific time window and not during any other opening hour of the same node. Useful for modeling time slots that require dedicated attention (e.g. a VIP appointment slot that cannot overlap with general availability).", "nullable" : true, "default" : false } }, "description" : "A time window during which a node is available for visits. Defined by a begin and end instant with a time zone. Supports preferred-window hints, sub-window offsets (e.g. lunch breaks), and exclusive solo-access mode. Multiple non-overlapping opening hours per node are supported." }, "OptimizationKeySetting" : { "type" : "object", "properties" : { "jsonLicense" : { "type" : "string", "description" : "The jsonLicense" } }, "description" : "The keySetting" }, "OptimizationOptions" : { "required" : [ "properties" ], "type" : "object", "properties" : { "properties" : { "type" : "object", "additionalProperties" : { "type" : "string", "description" : "The properties of the Optimization run. For example, the number of iterations for the Optimization run or the weight for certain Optimization goals can be defined." }, "description" : "The properties of the Optimization run. For example, the number of iterations for the Optimization run or the weight for certain Optimization goals can be defined." }, "optimizationSchemeOptions" : { "$ref" : "#/components/schemas/OptimizationSchemeOptions" } }, "description" : "Runtime configuration for the optimization engine. Contains a key-value property map that controls solver behavior — including iteration counts, algorithm weights, CPU core allocation, cost function tuning, and convergence criteria. Additionally, an optional optimizationSchemeOptions object can specify the exact construction and heuristic algorithm pipeline to execute. If omitted, the optimizer uses its built-in defaults." }, "OptimizationPersistenceSetting" : { "type" : "object", "properties" : { "mongoSettings" : { "$ref" : "#/components/schemas/MongoOptimizationPersistenceSetting" } }, "description" : "The persistenceSetting" }, "OptimizationPersistenceStrategySetting" : { "type" : "object", "properties" : { "saveConnections" : { "type" : "boolean", "description" : "The saveConnections. Only takes action if saveOnlyResult is false.", "example" : false } }, "description" : "The optimizationPersistenceStrategySetting" }, "OptimizationSchemeOptions" : { "required" : [ "constructionOptimizationAlgorithmConfig", "heuristicOptimizationAlgorithmConfigs" ], "type" : "object", "properties" : { "constructionOptimizationAlgorithmConfig" : { "$ref" : "#/components/schemas/ConstructionOptimizationAlgorithmConfig" }, "heuristicOptimizationAlgorithmConfigs" : { "type" : "array", "description" : "An ordered list of heuristic algorithm configurations that are executed sequentially after construction. Each entry defines an algorithm (e.g. Genetic Algorithm, Simulated Annealing) and its parameters (iteration count, repetitions). The optimizer runs each phase in order to progressively improve the solution.", "items" : { "$ref" : "#/components/schemas/HeuristicOptimizationAlgorithmConfig" } } }, "description" : "Defines the algorithm pipeline for an optimization run. Specifies exactly which construction heuristic builds the initial solution and which heuristic improvement phases (e.g. Genetic Algorithm, Simulated Annealing) are executed in sequence afterward. Each phase carries its own parameter set (iteration count, repetitions). If omitted from OptimizationOptions, the optimizer uses its built-in default pipeline." }, "OptimizationStatus" : { "required" : [ "error", "status", "statusDescription" ], "type" : "object", "properties" : { "statusDescription" : { "type" : "string", "description" : "A human-readable description of the optimization outcome (e.g. 'SUCCESS_WITH_SOLUTION', 'Optimization execution failed due to timeout'). Provides more context than the status tag alone." }, "error" : { "type" : "string", "description" : "An error code or message describing the failure cause. Set to 'NO_ERROR' on successful runs. On failure, contains the exception message or a structured error identifier for programmatic handling." }, "status" : { "type" : "string", "description" : "The machine-readable status tag indicating the optimization outcome. UNKNOWN: status not yet determined. ERROR: the run failed. SUCCESS_WITH_SOLUTION: completed with a valid solution. SUCCESS_WITHOUT_SOLUTION: completed but no feasible assignment was found.", "enum" : [ "UNKNOWN", "ERROR", "SUCCESS_WITH_SOLUTION", "SUCCESS_WITHOUT_SOLUTION" ] } }, "description" : "The status of the optimization" }, "PillarType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "A pillar (anchored/captured) node that is locked to a specific resource and cannot be reassigned during optimization. Subtypes include geo-pillar nodes (with latitude/longitude) and event-pillar nodes (non-geographical tasks).", "discriminator" : { "propertyName" : "typeName", "mapping" : { "GeoPillarNode" : "#/components/schemas/GeoPillarNode", "EventPillarNode" : "#/components/schemas/EventPillarNode" } } }, "PluginSetting" : { "required" : [ "isActive", "jsonSetting", "pluginName" ], "type" : "object", "properties" : { "pluginName" : { "type" : "string", "description" : "The pluginName" }, "jsonSetting" : { "type" : "string", "description" : "The jsonSetting" }, "isActive" : { "type" : "boolean", "description" : "The plugin can be deactivated. By default, if a setting exists, the plugin is also activated" } }, "description" : "The plugins" }, "PluginSettings" : { "required" : [ "plugins" ], "type" : "object", "properties" : { "plugins" : { "type" : "array", "description" : "The plugins", "items" : { "$ref" : "#/components/schemas/PluginSetting" } } }, "description" : "The PluginSettings" }, "Position" : { "required" : [ "latitude", "longitude" ], "type" : "object", "properties" : { "latitude" : { "type" : "number", "description" : "The latitude of the position", "format" : "double", "example" : 48.384037 }, "longitude" : { "type" : "number", "description" : "The longitude of the position", "format" : "double", "example" : 10.005226 }, "locationId" : { "type" : "string", "description" : "An optional location identifier that links this position to a shared location. Elements with the same locationId share the same geographic coordinates and connection data, reducing input size.", "example" : "MyLocationId" }, "geoAddress" : { "$ref" : "#/components/schemas/GeoAddress" }, "locationParameters" : { "$ref" : "#/components/schemas/LocationParameters" } }, "description" : "The end position of the route." }, "Qualification" : { "required" : [ "type" ], "type" : "object", "properties" : { "type" : { "$ref" : "#/components/schemas/QualificationType" } }, "description" : "The qualifications of the Resource." }, "QualificationType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "A resource-side qualification that declares what skills, territories, or capabilities a resource offers. Matched against node-level constraints during optimization. Subtypes include type-based qualifications (with optional expertise levels), zone number and UK post code qualifications, and high-performance bitset-based type qualifications (with optional expertise).", "discriminator" : { "propertyName" : "typeName", "mapping" : { "Type" : "#/components/schemas/TypeQualification", "TypeWithExpertise" : "#/components/schemas/TypeWithExpertiseQualification", "ZoneNumberQualification" : "#/components/schemas/ZoneNumberQualification", "UKPostCodeQualification" : "#/components/schemas/UKPostCodeQualification", "BitType" : "#/components/schemas/BitTypeQualification", "BitTypeWithExpertise" : "#/components/schemas/BitTypeWithExpertiseQualification" } } }, "RangeDay" : { "type" : "object", "description" : "Matches any day of the month within the interval [from.day, to.day] (inclusive). typeName must be \"Range.Day\".", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "from" : { "$ref" : "#/components/schemas/Day" }, "to" : { "$ref" : "#/components/schemas/Day" } } } ] }, "RangeDayMonth" : { "type" : "object", "description" : "Matches any month-day combination within the interval [from, to] (inclusive). typeName must be \"Range.DayMonth\".", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "from" : { "$ref" : "#/components/schemas/DayMonth" }, "to" : { "$ref" : "#/components/schemas/DayMonth" } } } ] }, "RangeDayMonthYear" : { "type" : "object", "description" : "Matches any full date within the interval [from, to] (inclusive). typeName must be \"Range.DayMonthYear\".", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "from" : { "$ref" : "#/components/schemas/DayMonthYear" }, "to" : { "$ref" : "#/components/schemas/DayMonthYear" } } } ] }, "RangeWeekDay" : { "type" : "object", "description" : "Matches any ISO weekday within the interval [from, to] (inclusive, wrapping). typeName must be \"Range.WeekDay\".", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "from" : { "$ref" : "#/components/schemas/WeekDay" }, "to" : { "$ref" : "#/components/schemas/WeekDay" } } } ] }, "ReducedNodeEdgeConnectorItem" : { "required" : [ "distance", "fromElementId", "time", "toElementId" ], "type" : "object", "properties" : { "distance" : { "type" : "string", "description" : "The distance of the hook connection.", "example" : "100.0 km" }, "time" : { "type" : "string", "description" : "The time needed to pass the hook connection.", "format" : "duration", "example" : "PT30M" }, "fromElementId" : { "type" : "string", "description" : "The fromElementId defines the element where the connections starts.", "example" : "MyStartElementId" }, "toElementId" : { "type" : "string", "description" : "The toElementId defines the element where the connections ends.", "example" : "MyToElementId" } }, "description" : "Pre-computed connections used exclusively during the construction hook phase. These connections override the default element connections for hook-related routing decisions, allowing special distance/time calculations during construction (e.g. depot-to-first-stop distances that differ from normal driving)." }, "RequestFlexLoad" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/ILoad" }, { "type" : "object", "properties" : { "loadId" : { "type" : "string" }, "isRequest" : { "type" : "boolean" }, "isFuzzyVisit" : { "type" : "boolean" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "RequestFlexLoad", "default" : "RequestFlexLoad" } } } ] }, "Resource" : { "required" : [ "id", "maxDistance", "maxTime", "position", "type", "workingHours" ], "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "The unique id of the Resource. It is not possible, to create mutliple elements (also Nodes) with the same id.", "example" : "MyResource" }, "extraInfo" : { "type" : "string", "description" : "A custom extra info string that is attached to the Resource.", "example" : "My custom extra info" }, "locationId" : { "type" : "string", "description" : "The location id can relate a Resouce to the connection of another resource. See also locationId of Node.", "example" : "MySecondResource" }, "constraintAliasId" : { "type" : "string", "description" : "The constraintAliasId. If set is used during constraint assessment instead of using the normal id.", "example" : "Jane" }, "type" : { "$ref" : "#/components/schemas/ResourceType" }, "position" : { "$ref" : "#/components/schemas/Position" }, "workingHours" : { "type" : "array", "description" : "The list of non-overlapping workingHours.", "items" : { "$ref" : "#/components/schemas/WorkingHours" } }, "maxTime" : { "type" : "string", "description" : "The maxTime. The maximal time a Resource should work within the WorkingHour. This value is NOT logically coupled to the workingHours. For example, a working hour is defined from 8 in the morning till 5 in the afternoon and the maxTime is defined as 4 hours. In this situation an overime violation will be already generated when the Resource works from 8 till 1 (one hour of overtime). As JOpt supports flexible start times, the Resource might work from 12-4 (4 hours => not violation). The workingHour itself should be seen as a frame that is used primarily for matching WokingHours of Resources and OpeningHours of nodes. If no flexTime is used, the Resource will always start working at the beginning of its current working hours.", "format" : "duration", "example" : "PT8H" }, "maxDistance" : { "type" : "string", "description" : "The maxDistance. The maximal distance a Resource is allowed to drive within a certain working hours.", "example" : "100.0 km" }, "destinationPosition" : { "$ref" : "#/components/schemas/Position" }, "stayOutDefinition" : { "$ref" : "#/components/schemas/StayOutDefinition" }, "stayOutCycleDefinition" : { "$ref" : "#/components/schemas/StayOutCycleDefinition" }, "stayOutPolicyTime" : { "type" : "string", "description" : "The maximum additional working time a resource is allowed to accumulate during an overnight-stay route beyond its normal working-hour boundaries. Acts as a buffer for late arrivals at stay nodes.", "format" : "duration", "example" : "PT1H" }, "stayOutPolicyDistance" : { "type" : "string", "description" : "The maximum additional driving distance a resource is allowed to accumulate during an overnight-stay route beyond its normal per-working-hour distance limit. Prevents the resource from driving excessively far to reach a stay node.", "example" : "100.0 km" }, "capacity" : { "type" : "array", "description" : "The multi-dimensional capacity vector of the resource (e.g. weight in kg, volume in m³, number of pallets). Each element represents the maximum capacity for one dimension. Used in pickup-and-delivery (PND) scenarios to enforce load constraints. The index positions must align with the load dimensions defined on the nodes.", "items" : { "type" : "number", "description" : "The multi-dimensional capacity vector of the resource (e.g. weight in kg, volume in m³, number of pallets). Each element represents the maximum capacity for one dimension. Used in pickup-and-delivery (PND) scenarios to enforce load constraints. The index positions must align with the load dimensions defined on the nodes.", "format" : "double" } }, "initialLoad" : { "type" : "array", "description" : "The initial load the resource carries at the start of each route, per capacity dimension. For delivery scenarios, this represents the pre-loaded goods at the depot. For pickup scenarios, this is typically zero. Must have the same dimensionality as the capacity vector.", "items" : { "type" : "number", "description" : "The initial load the resource carries at the start of each route, per capacity dimension. For delivery scenarios, this represents the pre-loaded goods at the depot. For pickup scenarios, this is typically zero. Must have the same dimensionality as the capacity vector.", "format" : "double" } }, "minDegratedCapacity" : { "type" : "array", "description" : "The minimum degraded capacity per dimension. As the resource visits more stops, its effective capacity may degrade (e.g. due to fatigue, compartment loss, or reorganization overhead). This vector defines the floor below which the capacity cannot degrade, regardless of the number of stops visited.", "items" : { "type" : "number", "description" : "The minimum degraded capacity per dimension. As the resource visits more stops, its effective capacity may degrade (e.g. due to fatigue, compartment loss, or reorganization overhead). This vector defines the floor below which the capacity cannot degrade, regardless of the number of stops visited.", "format" : "double" } }, "capacityDegPerStop" : { "type" : "array", "description" : "The capacity degradation per stop, per dimension. After each node visit, the resource's effective capacity is reduced by this amount (down to the minDegratedCapacity floor). Models real-world effects such as compartment unavailability after partial unloading or diminishing usable space.", "items" : { "type" : "number", "description" : "The capacity degradation per stop, per dimension. After each node visit, the resource's effective capacity is reduced by this amount (down to the minDegratedCapacity floor). Models real-world effects such as compartment unavailability after partial unloading or diminishing usable space.", "format" : "double" } }, "startReductionTimeDefinition" : { "$ref" : "#/components/schemas/StartReductionTimeDefinition" }, "startReductionTimePillarDefinition" : { "$ref" : "#/components/schemas/StartReductionTimePillarDefinition" }, "startReductionTimeIncludeDefinition" : { "$ref" : "#/components/schemas/StartReductionTimeIncludeDefinition" }, "flexTime" : { "type" : "string", "description" : "The local flexible time. In some cases a Resource should start working later compared to what is defined in the working hours. This way idle time can be reduced. The local flex time is the maximum a Resource is allowed to start working later, depending on the Optimization maybe flex time is not or only partially used.", "format" : "duration", "example" : "PT1H" }, "postFlexTime" : { "type" : "string", "description" : "The maximum duration by which the resource is allowed to end its working day earlier than the working-hour boundary. Reduces unnecessary idle time at the end of a route. See also postFlexTimeOnlyOnOvertime to restrict usage to overtime-reduction scenarios.", "format" : "duration", "example" : "PT1H" }, "postFlexTimeOnlyOnOvertime" : { "type" : "boolean", "description" : "The post flextime is only applied to reduce overtime.", "nullable" : true, "default" : false }, "maxPillarAfterHoursTime" : { "type" : "string", "description" : "The maximum duration a pillar node may be served after the resource's official working-hours end. Applies globally across all working hours of this resource. For per-working-hour overrides, use maxLocalPillarAfterHoursTime on the individual WorkingHours object.", "format" : "duration", "example" : "PT1H" }, "maxDriveTimeFirstNode" : { "type" : "string", "description" : "The maximum driving time allowed from the resource's start position to the first node of a route. Prevents the optimizer from assigning a distant first stop that would consume excessive travel time before productive work begins.", "format" : "duration", "example" : "PT1H" }, "maxDriveDistanceFirstNode" : { "type" : "string", "description" : "The maximum driving distance allowed from the resource's start position to the first node of a route. Complements maxDriveTimeFirstNode to enforce both time- and distance-based proximity constraints.", "example" : "100.0 km" }, "maxDriveTimeLastNode" : { "type" : "string", "description" : "The maximum driving time allowed from the last visited node to the route termination element (typically the resource's home position or alternate destination). Prevents the optimizer from placing a final stop that would require an excessively long return journey.", "format" : "duration", "example" : "PT1H" }, "maxDriveDistanceLastNode" : { "type" : "string", "description" : "The maximum driving distance allowed from the last visited node to the route termination element. Complements maxDriveTimeLastNode to enforce both time- and distance-based return constraints.", "example" : "100.0 km" }, "kilometerCost" : { "type" : "number", "description" : "The kilometerCost defines how much arbitrary cost arises per kilometer driven.", "format" : "double" }, "hourCost" : { "type" : "number", "description" : "The hourCost defines how much arbitrary cost arises per hour scheduled (idling, working, driving).", "format" : "double" }, "productionHourCost" : { "type" : "number", "description" : "The productionHourCost defines how much arbitrary cost arises per hour working.", "format" : "double" }, "fixCost" : { "type" : "number", "description" : "The fixCost defines an abstract cost that arrises when this node is visited.", "format" : "double" }, "preWorkDrivingTime" : { "type" : "string", "description" : "DEPRECATED. Use startReductionTimeDefinition instead. Legacy field that defined how long before the official working-hour start the resource was allowed to drive.", "format" : "duration", "example" : "PT1H", "deprecated" : true }, "skillEfficiencyFactor" : { "type" : "number", "description" : "DEPRECATED. Use the visitDurationEfficiency mechanism on individual nodes and ResourceVisitDurationEfficiency instead. Legacy factor that scaled visit durations for this resource.", "format" : "double", "deprecated" : true }, "acceptableOvertime" : { "type" : "string", "description" : "The acceptableOvertime. By default if nodes are constantly leading to overtime for a resource, at some point they might get unassigned (if AutoFilter is activated). The acceptable overtime assigns a margin to avoid filtering nodes if they lead to overtime below this margin. By defaul the property 'JoptAutoFilterWorkingHoursExceedMargin' can be used to globally define this value.", "format" : "duration", "example" : "PT1H" }, "strictOvertime" : { "type" : "string", "description" : "The strictOvertime. By default if nodes are constantly leading to overtime for a resource, at some point they might get unassigned (if AutoFilter is activated). The strictOvertime overtime assigns a margin to avoid filtering nodes if they lead to overtime below this margin. By defaul the property 'JoptAutoFilterWorkingHoursStrictExceedMargin' can be used to globally define this value. In contrast to acceptable overtime, the strict overtime is used during the last fitlering step of the AutoFilter (if strict mode is enabled).", "format" : "duration", "example" : "PT2H" }, "acceptableOverdistance" : { "type" : "string", "description" : "The acceptableOverdistance. Like acceptableOvertime for distance.", "example" : "100.0 km" }, "strictOverdistance" : { "type" : "string", "description" : "The strictOverdistance. Like strictOvertime for distance.", "example" : "100.0 km" }, "averageSpeed" : { "type" : "number", "description" : "The averageSpeed of the Resource. By default this value is set to be 22[m/s] (79.2[km/h]). This value is mainly used, in case no external node connections are provided.", "format" : "double" }, "qualifications" : { "type" : "array", "description" : "The qualifications of the Resource.", "items" : { "$ref" : "#/components/schemas/Qualification" } }, "constraints" : { "type" : "array", "description" : "The constraints of the Resource", "items" : { "$ref" : "#/components/schemas/Constraint" } }, "connectionTimeEfficiencyFactor" : { "type" : "number", "description" : "The connectionTimeEfficiencyFactor. The default time for passing a connection is devided by this factor. For example, if a connections needs 30 minutes to be passed by default, a Resource with a connectionTimeEfficiencyFactor of 1.5 only needs 20 minutes. By default this factor is one.", "format" : "double", "example" : 1.5, "default" : 1.0 }, "co2emissionFactor" : { "type" : "number", "description" : "The co2emissionFactor.", "format" : "double", "example" : 0.377 }, "resourceDepot" : { "$ref" : "#/components/schemas/IResourceDepot" }, "overallVisitDurationEfficiency" : { "type" : "number", "description" : "The overallVisitDurationEfficiency. The base duration a Resource spends at a node is devided by this factor. For example, if a node has 30 minutes of visit duration assigned, a Resource with a overallVisitDurationEfficiency of 1.5 only needs 20 minutes. By default this factor is one.", "format" : "double", "example" : 1.5, "default" : 1.0 }, "isReductionTimeIncludedInTotalWorkingTime" : { "type" : "boolean", "description" : "DEPRECATED. Use StartReductionTimeIncludeDefinition instead. Legacy flag that controlled whether reduction time was counted toward the resource's total working time.", "nullable" : true, "deprecated" : true, "default" : false }, "isServiceHub" : { "type" : "boolean", "description" : "A resource is hub mode gets visited by nodes.", "nullable" : true, "default" : false }, "isReductionTimeOnlyUsedForDriving" : { "type" : "boolean", "description" : "DEPRECATED. Use startReductionTimeDefinition instead. Legacy flag that restricted reduction time to driving only (no working at the first node before the shift starts).", "nullable" : true, "deprecated" : true, "default" : false } }, "description" : "A mobile agent (vehicle, driver, technician) available to visit nodes. Defines a home position, one or more working-hour windows with time/distance constraints, optional qualifications (skills), an optional resource depot for pickup-and-delivery, connection efficiency factors, overnight-stay policies, and route configuration (open/closed, alternate destination, return-to-start)." }, "ResourceLocationConstraint" : { "required" : [ "typeName" ], "type" : "object", "description" : "A constraint that limits a node to be visited only by resources within a maximum distance or travel time radius. At least one of maxRadiusDistance or maxRadiusTime must be provided. NOTE: This constraint type is currently under review and may not function as expected in all scenarios.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "maxRadiusDistance" : { "type" : "string", "description" : "The maximum Euclidean or road-network distance a resource may be located from this node in order to be eligible to visit it. If omitted, only maxRadiusTime is enforced.", "example" : "100.0 km" }, "maxRadiusTime" : { "type" : "string", "description" : "The maximum travel time a resource may need to reach this node in order to be eligible to visit it. If omitted, only maxRadiusDistance is enforced.", "format" : "duration", "example" : "PT2H" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "ResourceLocationConstraint", "default" : "ResourceLocationConstraint" } } } ] }, "ResourceTrip" : { "required" : [ "fromElementId", "line", "toElementId" ], "type" : "object", "properties" : { "line" : { "$ref" : "#/components/schemas/EncodedPolyline" }, "fromElementId" : { "type" : "string", "description" : "The position the polyline starts." }, "toElementId" : { "type" : "string", "description" : "The position the polyline ends." }, "rawJson" : { "$ref" : "#/components/schemas/JsonNode" } }, "description" : "A single trip segment between two elements on a route. Contains an encoded polyline for map rendering, the source and destination element ids, and optional raw JSON with additional trip metadata from the routing provider." }, "ResourceType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "The polymorphic resource definition used in the optimization input. Currently supports capacity-based resources that carry working hours, location, and optional depot/load capacity configuration.", "discriminator" : { "propertyName" : "typeName", "mapping" : { "Capacity" : "#/components/schemas/CapacityResource" } } }, "ResourceWithPriority" : { "required" : [ "priority", "resourceId" ], "type" : "object", "properties" : { "resourceId" : { "type" : "string", "description" : "The resourceId that will be part of a constraint. For example, Jack is a preffered Resource of a node. If multiple resources are preferred, the Optimizer tries to schedule the Resource with the highest priority.", "example" : "Alex" }, "priority" : { "type" : "integer", "description" : "The scheduling priority for this resource within the constraint. When multiple resources are eligible, the optimizer prefers the one with the highest priority value.", "format" : "int32", "example" : 5 } }, "description" : "The list of resources that should NOT visit a certain node." }, "RestOptimization" : { "required" : [ "nodes", "resources" ], "type" : "object", "properties" : { "optimizationStatus" : { "$ref" : "#/components/schemas/OptimizationStatus" }, "id" : { "type" : "string", "description" : "A system-generated unique identifier assigned by the persistence layer (e.g. MongoDB ObjectId). This field is read-only and will be populated automatically when the optimization snapshot is stored in the database. Clients may use this value together with the creator field to retrieve or reference a specific persisted snapshot.", "example" : "626ba175a9d4fa6d6beec158" }, "createdTimeStamp" : { "type" : "integer", "description" : "An epoch-millisecond timestamp recording when this optimization snapshot was created. Populated automatically by the server at persistence time. Used for chronological ordering and expiry management Do not set this field in the input — it will be overwritten.", "format" : "int64" }, "creator" : { "type" : "string", "description" : "A tenant-scoped identifier for the entity that submitted this optimization. Typically derived as a SHA-256 hash of the creator name supplied in the request's creatorSetting. Used as the primary scoping key for database queries — all persistence read operations require the creator to match, ensuring tenant isolation in multi-tenant deployments. Populated automatically by the server; do not set this field in the input.", "example" : "11aa65b13c2a6d34f8727e82e403ce869e3bba1d35c45c595e8cc5ce5e74e57a" }, "ident" : { "type" : "string", "description" : "A user-defined, human-readable label for this optimization run. Useful for distinguishing runs in database queries and audit logs (e.g. 'Weekly-Route-Plan-CW42' or 'NightShift-Berlin'). If not provided, the server generates a default identifier based on a timestamp. Note: this field is stored as unencrypted metadata even when payload encryption is enabled — avoid embedding sensitive business information.", "example" : "JOpt-Run-603886271000" }, "nodes" : { "type" : "array", "description" : "The list of nodes (work items, customer locations, or events) to be scheduled and assigned to resources. Each node defines a geographic or event-based location, one or more opening-hour windows, a required visit duration, and optional constraints (skill requirements, resource bindings, priority, pickup-and-delivery loads). Every node id must be globally unique across all nodes and resources in this configuration.", "items" : { "$ref" : "#/components/schemas/Node" } }, "resources" : { "type" : "array", "description" : "The list of resources (vehicles, drivers, technicians, or other mobile agents) available to visit the defined nodes. Each resource specifies a home position, one or more working-hour windows, maximum working time and distance constraints, optional qualifications (skills), an optional alternate destination, and overnight-stay policies. Resource ids must be globally unique across all elements.", "items" : { "$ref" : "#/components/schemas/Resource" } }, "nodeRelations" : { "type" : "array", "description" : "The list of inter-node relations that impose ordering or co-assignment constraints between nodes. Supported relation types include SAME_ROUTE (nodes must be on the same route), SAME_VISITOR (nodes must be served by the same resource), DIFFERENT_ROUTE (nodes must not share a route), and relative time-window relations that enforce temporal precedence (e.g. node A must be visited before node B within a defined time gap).", "items" : { "$ref" : "#/components/schemas/NodeRelation" } }, "elementConnections" : { "type" : "array", "description" : "Pre-computed pairwise connections between elements (nodes and resources). Each connection specifies the travel distance and time between a source and a target element, optionally including time-dependent traffic profiles via connectionByTime. If connections are not provided, the optimizer falls back to a Haversine-based distance approximation or a configured backup connector. Providing accurate connections significantly improves solution quality. In persisted results, this list may be omitted to conserve storage (controlled via saveConnections).", "items" : { "$ref" : "#/components/schemas/ElementConnection" } }, "zoneConnections" : { "type" : "array", "description" : "Zone connections define penalties or restrictions for crossing geographic zone boundaries (e.g. bridge tolls, tunnel crossings, or administrative borders). Each ZoneConnection specifies a pair of zone numbers and an associated crossing cost. When a route transitions between zones, the optimizer accumulates these costs, which discourages unnecessary zone crossings and promotes geographically cohesive routes.", "items" : { "$ref" : "#/components/schemas/ZoneConnection" } }, "typeDictionaries" : { "$ref" : "#/components/schemas/TypeDictionaries" }, "optimizationOptions" : { "$ref" : "#/components/schemas/OptimizationOptions" }, "coreBuildOptions" : { "$ref" : "#/components/schemas/CoreBuildOptions" }, "solution" : { "$ref" : "#/components/schemas/Solution" }, "extension" : { "$ref" : "#/components/schemas/JSONConfig" } }, "description" : "The REST-specific specialization of OptimizationConfig with JSONConfig as the extension type. This is the top-level request/response object for the TourOptimizer REST API. Inherits all fields from OptimizationConfig and adds JSON-specific extension support for license keys, persistence settings, creator settings, and timeout configuration.", "example" : { "ident" : "JOpt-Run-1789459529683", "nodes" : [ { "id" : "Koeln", "type" : { "position" : { "latitude" : 50.9333, "longitude" : 6.95, "locationId" : "Koeln" }, "typeName" : "Geo" }, "openingHours" : [ { "begin" : "2020-03-06T07:00:00Z", "end" : "2020-03-06T16:00:00Z", "zoneId" : "Europe/Berlin" } ], "visitDuration" : "PT20M", "priority" : 1 }, { "id" : "Oberhausen", "type" : { "position" : { "latitude" : 51.4667, "longitude" : 6.85, "locationId" : "Oberhausen" }, "typeName" : "Geo" }, "openingHours" : [ { "begin" : "2020-03-06T07:00:00Z", "end" : "2020-03-06T16:00:00Z", "zoneId" : "Europe/Berlin" } ], "visitDuration" : "PT20M", "priority" : 1 }, { "id" : "Essen", "type" : { "position" : { "latitude" : 51.45, "longitude" : 7.01667, "locationId" : "Essen" }, "typeName" : "Geo" }, "openingHours" : [ { "begin" : "2020-03-06T07:00:00Z", "end" : "2020-03-06T16:00:00Z", "zoneId" : "Europe/Berlin" } ], "visitDuration" : "PT20M", "priority" : 1 }, { "id" : "Cologne Pillar", "type" : { "position" : { "latitude" : 50.9333, "longitude" : 6.95, "locationId" : "Cologne Pillar" }, "pillarNode" : { "onlyScheduledInCompany" : false, "typeName" : "GeoPillarNode", "isAutoTransformable2StartAnchor" : false, "isOverwritingRouteStart" : false, "isOverwritingRouteTermination" : false, "isSchedulableAfterWorkingHours" : false, "isSchedulableBeforeWorkingHours" : false, "isTimeAdjustableAnchor" : false, "isForcedStayNode" : false }, "typeName" : "Geo" }, "openingHours" : [ { "begin" : "2020-03-06T07:00:00Z", "end" : "2020-03-06T16:00:00Z", "zoneId" : "Europe/Berlin" } ], "visitDuration" : "PT20M", "priority" : 1 }, { "id" : "Cologne Pillar Event", "type" : { "pillarNode" : { "onlyScheduledInCompany" : false, "typeName" : "EventPillarNode", "isOverwritingRouteTermination" : false, "isSchedulableAfterWorkingHours" : false, "isSchedulableBeforeWorkingHours" : false, "isTimeAdjustableAnchor" : false, "isExtendableEnd" : false }, "typeName" : "Event" }, "openingHours" : [ { "begin" : "2020-03-06T07:00:00Z", "end" : "2020-03-06T16:00:00Z", "zoneId" : "Europe/Berlin" } ], "visitDuration" : "PT20M", "priority" : 1 } ], "resources" : [ { "id" : "Jack", "type" : { "typeName" : "Capacity" }, "position" : { "latitude" : 50.775346, "longitude" : 6.083887, "locationId" : "Jack" }, "workingHours" : [ { "begin" : "2020-03-06T07:00:00Z", "end" : "2020-03-06T16:00:00Z", "zoneId" : "Europe/Berlin" }, { "begin" : "2020-03-07T07:00:00Z", "end" : "2020-03-07T19:00:00Z", "zoneId" : "Europe/Berlin" } ], "maxTime" : "PT8H", "maxDistance" : "1200 km", "co2emissionFactor" : 0.377 } ], "optimizationOptions" : { "properties" : { "JOpt.Algorithm.GE.OnProgressOutPercentage" : "1.0", "JOpt.Algorithm.Operator.2Opt.Threshold" : "10", "JOpt.Algorithm.Operator.GE.doForceReselect" : "FALSE", "JOpt.Algorithm.Operator.GE.numReselects" : "3", "JOpt.Algorithm.Operator.RequireHoursOverlap" : "TRUE", "JOpt.Algorithm.Operator.SA.doForceReselect" : "FALSE", "JOpt.Algorithm.Operator.SA.numReselects" : "5", "JOpt.Algorithm.PreOptimization.SA.CoolingRate" : "0.999985", "JOpt.Algorithm.PreOptimization.SA.NumIterations" : "150000", "JOpt.Algorithm.PreOptimization.SA.NumRepetions" : "1", "JOpt.Algorithm.PreOptimization.SA.OnProgressOutPercentage" : "1.0", "JOpt.Algorithm.PreOptimization.SA.StartingTemperature" : "10.0", "JOpt.Algorithm.PreOptimization.SA.StartingTemperatureLoadedSnapshot" : "0.1", "JOpt.Algorithm.Relation.NestingLimit" : "100", "JOpt.Algorithm.tryUseCluster2Opt" : "FALSE", "JOpt.Algorithm.tryUseClusterInsertion" : "FALSE", "JOpt.Assisted" : "TRUE", "JOpt.AutoFilter" : "FALSE", "JOpt.AutoFilter.EarlyArrivalMargin" : "0", "JOpt.AutoFilter.LateArrivalMargin" : "0", "JOpt.AutoFilter.RouteDistanceExceedMargin" : "0", "JOpt.AutoFilter.WorkingHoursExceedMargin" : "0", "JOpt.AutoFilter.afterFilteringResult" : "FALSE", "JOpt.AutoFilter.beforeFilteringResult" : "FALSE", "JOpt.AutoFilter.canDisableNodeProtection" : "TRUE", "JOpt.AutoFilter.collectivePenalization.maxImportance" : "5", "JOpt.AutoFilter.tryAvoidSplittingJoinedClusters" : "FALSE", "JOpt.AutoFilter.tryGracefulNodeFiltering" : "TRUE", "JOpt.AutoFilter.usePostOptimizationAfterStrictFiltering" : "TRUE", "JOpt.AutoFilter.useStrictFilterOnLastExecution" : "TRUE", "JOpt.AutoForceFilter.EarlyArrivalMargin" : "0", "JOpt.AutoForceFilter.LateArrivalMargin" : "0", "JOpt.AutoForceFilter.RouteDistanceExceedMargin" : "0", "JOpt.AutoForceFilter.WorkingHoursExceedMargin" : "0", "JOpt.CO.ActiveTimeTrigger" : "FALSE", "JOpt.CO.AutoSyncJoptTime" : "FALSE", "JOpt.CapacityDegradation.TreatSameLocationsAsOne" : "FALSE", "JOpt.Clustering.AutoZoneCodeClusters" : "FALSE", "JOpt.Clustering.AutoZoneCodeClusters.isHard" : "FALSE", "JOpt.Clustering.JointVisitDuration.doUseDistanceDivider" : "FALSE", "JOpt.Clustering.MaxDistanceUtilization" : "200.0", "JOpt.Clustering.MaxDurationUtilization" : "80.0", "JOpt.Clustering.PenlalizeZoneCodeCrossing" : "FALSE", "JOpt.Clustering.PenlalizeZoneCodeCrossingMultiplier" : "1.0", "JOpt.Clustering.ReassignOrphanedNodes" : "TRUE", "JOpt.Clustering.ResourceDutyHoursSplitValue" : "10", "JOpt.Clustering.ResourceSplitValue" : "30", "JOpt.Clustering.ShowDebugOutput" : "FALSE", "JOpt.CostAssessment.suppressInactiveFinalizedRouteCosts" : "TRUE", "JOpt.CostAssessment.useAverageCost" : "FALSE", "JOpt.DebugMode.NodeChecking" : "TRUE", "JOpt.EntityValidation.Debug" : "FALSE", "JOpt.FuzzyDemand" : "0", "JOpt.IntermediateStage.ThrowResults" : "FALSE", "JOpt.JOptPopulationSize" : "100", "JOpt.JointVisitDuration.maxRadiusMeter" : "10.0", "JOpt.JointVisitDuration.routeTimeBonusFactor" : "0.0", "JOpt.KeepZeroDriveForEventNodes" : "FALSE", "JOpt.Lockdown.Blockpillar.endOffset" : "0", "JOpt.Lockdown.Blockpillar.startOffset" : "0", "JOpt.Lockdown.LockdownUnchangedRoutes" : "TRUE", "JOpt.MovingEventNodes" : "TRUE", "JOpt.Multicore" : "1", "JOpt.NumCPUCores" : "4", "JOpt.PerformanceMode" : "FALSE", "JOpt.PillarDropper.AllowRescheduleMaximalRouteDistanceExceeded" : "TRUE", "JOpt.PillarDropper.AllowRescheduleWorkingHoursExceeded" : "TRUE", "JOpt.PlausibilityGuard.PropertyChecker.Active" : "TRUE", "JOpt.PropertyChecker.ShowWarnings" : "TRUE", "JOpt.ReassignNodesOnStartup" : "FALSE", "JOpt.SelectiveAutoFilter" : "FALSE", "JOpt.SelectiveAutoFilter.AfterEndAnchor" : "FALSE", "JOpt.SelectiveAutoFilter.CapacityOverload" : "FALSE", "JOpt.SelectiveAutoFilter.DoubleBooking" : "FALSE", "JOpt.SelectiveAutoFilter.MaximalRouteDistanceExceeded" : "FALSE", "JOpt.SelectiveAutoFilter.NodeType" : "FALSE", "JOpt.SelectiveAutoFilter.RelationShip" : "FALSE", "JOpt.SelectiveAutoFilter.ResourceMismatch" : "FALSE", "JOpt.SelectiveAutoFilter.TimeWindow.Early" : "FALSE", "JOpt.SelectiveAutoFilter.TimeWindow.Late" : "FALSE", "JOpt.SelectiveAutoFilter.WorkingHoursExceeded" : "FALSE", "JOpt.UnlocatedIdleTime" : "FALSE", "JOpt.plausibility.doInputCheck" : "TRUE", "JOpt.plausibility.doInputCheck.doCapacityCheck" : "TRUE", "JOptExitCondition.JOptGenerationCount" : "5000", "JOptWeight.CO2Emission" : "0.0", "JOptWeight.Capacity" : "50.0", "JOptWeight.ColorCapacity" : "10.0", "JOptWeight.CompactingFactor" : "1.0", "JOptWeight.DistanceExceeded" : "10.0", "JOptWeight.DistanceVariationPattern" : "0.0", "JOptWeight.ExpertiseLevelPreference" : "1.0", "JOptWeight.NodeCompactingFactor" : "0.0", "JOptWeight.NodeImportance" : "1.0", "JOptWeight.NodeType" : "1.0", "JOptWeight.PreferableResource" : "1.0", "JOptWeight.Relationships" : "100.0", "JOptWeight.ResourceActive" : "0.0", "JOptWeight.ResourceLocationBias" : "0.0", "JOptWeight.ResourceRadiusDrivingDistance" : "1.0", "JOptWeight.ResourceRadiusDrivingTime" : "1.0", "JOptWeight.ResourceWorkingTimeBalance" : "0.0", "JOptWeight.RouteDistance" : "1.0", "JOptWeight.RouteTime" : "1.0", "JOptWeight.TimeExceeded" : "100.0", "JOptWeight.TimeWindow" : "1.0", "JOptWeight.TimeWindow.AfterEndPillarAnchor" : "1000.0", "JOptWeight.TimeWindow.FlexTimePenalizeFactor" : "0.0", "JOptWeight.TimeWindow.OfferedNodeCostMulitplier" : "2.0", "JOptWeight.TimeWindow.ServiceHours" : "10.0", "JOptWeight.TimeWindow.TimeWindowEarlyFactor" : "10.0", "JOptWeight.TimeWindow.TimeWindowEarlyFactorAtFirstNode" : "1.0", "JOptWeight.TimeWindow.TimeWindowLateFactor" : "100.0", "JOptWeight.TotalDistance" : "1.0", "JOptWeight.TotalTime" : "1.0", "JOptWeight.UnPreferableResource" : "1.0", "JOptWeight.UselessUnloadAllVisitation" : "1.0", "JOptWeight.WorkingTime" : "5.0", "JOptWeight.ZoneCode" : "10.0" }, "optimizationSchemeOptions" : { "constructionOptimizationAlgorithmConfig" : { "algorithm" : "SMART_CONSTR_ALGO" }, "heuristicOptimizationAlgorithmConfigs" : [ { "algorithm" : "SMART_SIMULATED_ANNEALING_ALGO", "hasAutoFilter" : false }, { "algorithm" : "GENETIC_EVOLUTION_ALGO", "hasAutoFilter" : true } ] } }, "coreBuildOptions" : { "buildCoreProperties" : { "jopt.core.maven-surefire-plugin.version" : "3.2.2", "jopt.core.errorprone.version" : "2.47.0", "jopt.core.git.commit.author.time" : "20260409-103532", "jopt.core.jopt.version.number" : "7.5.3-rc2-j17", "jopt.core.jackson-databind.version" : "2.21.0", "jopt.core.git.dirty" : "false", "jopt.core.dna.nexus.maven.obfuscated.releases.new" : "https://nexus.dna-evolutions.net/repository/maven-releases/", "jopt.core.testng.version" : "7.12.0", "jopt.core.proguard.core.version" : "9.3.0", "jopt.core.git.build.host" : "cb03467e-fd02-4d9e-88ec-11fcdecad52a-kptvv", "jopt.core.git.build.time" : "20260409-104123", "jopt.core.jackson-datatype-guava.version" : "2.21.0", "jopt.core.git.commit.user.name" : "Jens Richter", "jopt.core.jackson-datatype-jdk8.version" : "2.21.0", "jopt.core.git.local.branch.ahead" : "NO_REMOTE", "jopt.core.spotbugs.version" : "4.9.8", "jopt.core.dna.nexus.maven.obfuscated.new" : "https://nexus.dna-evolutions.net/repository/maven-public/", "jopt.core.maven-shade-plugin.version" : "3.5.1", "jopt.core.bson.version" : "5.6.1", "jopt.core.git.closest.tag.commit.count" : "0", "jopt.core.maven-deploy-plugin.version" : "3.1.1", "jopt.core.commons-math3.version" : "3.6.1", "jopt.core.jacoco-maven-plugin.version" : "0.8.8", "jopt.core.maven.compiler.target" : "17", "jopt.core.unit-api.version" : "2.2", "jopt.core.jopt.version.postfix" : "", "jopt.core.project.build.sourceEncoding" : "UTF-8", "jopt.core.dna.nexus.maven.public.new" : "https://private-nexus.dna-evolutions.net/repository/maven-public/", "jopt.core.git.branch" : "f44c2fa07b7fa5661fdd020a92f285168f3014e0", "jopt.core.git-commit-id-plugin.version" : "4.9.10", "jopt.core.maven-javadoc-plugin.version" : "3.6.3", "jopt.core.dna.nexus.maven.releases.new" : "https://private-nexus.dna-evolutions.net/repository/maven-releases/", "jopt.core.log4j-core.version" : "2.25.3", "jopt.core.maven-source-plugin.version" : "3.3.0", "jopt.core.spring-data-mongodb.version" : "4.5.8", "jopt.core.datafactory.version" : "0.8", "jopt.core.commons-compress.version" : "1.28.0", "jopt.core.dna.nexus.maven.snapshots.new" : "https://private-nexus.dna-evolutions.net/repository/maven-snapshots/", "jopt.core.java.version.target" : "17", "jopt.core.jackson-datatype-jsr310.version" : "2.21.0", "jopt.core.build.time.utc" : "2026-04-09T10:41:14Z", "jopt.core.git.commit.id.describe" : "v7.5.3-rc2", "jopt.core.dna.nexus.maven.obfuscated.snapshots.new" : "https://nexus.dna-evolutions.net/repository/maven-snapshots/", "jopt.core.java.version.source" : "17", "jopt.core.properties-maven-plugin.version" : "1.1.0", "jopt.core.value.version" : "2.12.1", "jopt.core.git.tags" : "v7.5.3-rc2", "jopt.core.git.commit.id" : "f44c2fa07b7fa5661fdd020a92f285168f3014e0", "jopt.core.poi.version" : "5.5.1", "jopt.core.git.commit.id.describe-short" : "v7.5.3-rc2", "jopt.core.dna.nexus.maven.endpoint.new" : "https://private-nexus.dna-evolutions.net", "jopt.core.commons-lang3.version" : "3.20.0", "jopt.core.maven.test.skip" : "true", "jopt.core.jackson-module-parameter-names.version" : "2.21.0", "jopt.core.maven.compiler.source" : "17", "jopt.core.dna.nexus.maven.obfuscated.endpoint.new" : "https://nexus.dna-evolutions.net", "jopt.core.git.local.branch.behind" : "NO_REMOTE", "jopt.core.git.build.number" : "2657", "jopt.core.git.commit.committer.time" : "20260409-103532", "jopt.core.git.build.version" : "7.5.3-rc2-j17", "jopt.core.git.commit.id.abbrev" : "f44c2fa", "jopt.core.guava.version" : "33.5.0-jre", "jopt.core.swagger-annotations.version" : "2.2.42", "jopt.core.license-maven-plugin.version" : "2.0.0", "jopt.core.unit-indriya.version" : "2.2.3", "jopt.core.jts-core.version" : "1.20.0", "jopt.core.javafaker.version" : "1.0.2", "jopt.core.git.total.commit.count" : "3536", "jopt.core.git.closest.tag.name" : "v7.5.3-rc2", "jopt.core.poi-ooxml.version" : "5.5.1", "jopt.core.git.commit.time" : "20260409-103532", "jopt.core.hamcrest.version" : "3.0", "jopt.core.maven-compiler-plugin.version" : "3.12.1", "jopt.core.proguard-maven-plugin.version" : "2.6.0", "jopt.core.proguard.base.version" : "7.8.2", "jopt.core.jackson-default.version" : "2.21.0", "jopt.core.rxjava.version" : "3.1.12" } }, "extension" : { "creatorSetting" : { "creator" : "PUBLIC_CREATOR" }, "keySetting" : { "jsonLicense" : "{\r\n \"version\" : \"1.2\",\r\n \"identifier\" : \"PUBLIC-\",\r\n \"description\" : \"Key provided to for evaluation purpose from DNA evolutions GmbH.\",\r\n \"contact\" : \"www.dna-evolutions.com\",\r\n \"modules\" : [ {\r\n \"Module:\" : \"Elements\",\r\n \"max\" : 20\r\n }, {\r\n \"Module:\" : \"Date\",\r\n \"creation\" : \"2025-02-04\",\r\n \"due\" : \"2029-01-28\"\r\n } ],\r\n \"key\" : \"PUBLIC-e6dc49fcbda599f45638d39794fd4f99b062c2ae96864e37ef\"\r\n}" }, "timeOut" : "PT5M" } } }, "Route" : { "required" : [ "elementDetails", "endElementId", "id", "nonOptimizableElementIds", "optimizableElementIds", "optionalOptimizableElementIds", "pillarElementIds", "resourceId", "startElementId", "startTime" ], "type" : "object", "properties" : { "header" : { "$ref" : "#/components/schemas/RouteHeader" }, "id" : { "type" : "integer", "description" : "The id is an optimizer provided number identifiying a route.", "format" : "int32", "example" : 11 }, "resourceId" : { "type" : "string", "description" : "The resourceId of the Visitor owning this route.", "example" : "Laura" }, "routeTrip" : { "$ref" : "#/components/schemas/RouteTrip" }, "startTime" : { "type" : "string", "description" : "The startTime of the route. This is usually the start of the workingHours of the Resource. However, when using flextime/reduction-time the starttime can be different from the working hours start.", "format" : "date-time", "example" : "2020-03-06T07:00:00Z" }, "startElementId" : { "type" : "string", "description" : "The startElementId, is the element from where the route starts. By default, it is the Resource itself.", "example" : "Laura" }, "startPosition" : { "$ref" : "#/components/schemas/Position" }, "endElementId" : { "type" : "string", "description" : "The endElementId, is the element where the route stops. By default, it is the Resource itself.", "example" : "Laura" }, "endPosition" : { "$ref" : "#/components/schemas/Position" }, "optimizableElementIds" : { "type" : "array", "description" : "The optimizableElementIds. The list of optimizable elements that are part of the route.", "items" : { "type" : "string", "description" : "The optimizableElementIds. The list of optimizable elements that are part of the route." } }, "nonOptimizableElementIds" : { "type" : "array", "description" : "The nonOptimizableElementIds. The list of non-optimizable elements that are part of the route.", "items" : { "type" : "string", "description" : "The nonOptimizableElementIds. The list of non-optimizable elements that are part of the route." } }, "optionalOptimizableElementIds" : { "type" : "array", "description" : "The optionalOptimizableElementIds. The list of optional elements that are part of the route.", "items" : { "type" : "string", "description" : "The optionalOptimizableElementIds. The list of optional elements that are part of the route." } }, "pillarElementIds" : { "type" : "array", "description" : "The pillarElementIds. The list of pillar elements that are part of the route.", "items" : { "type" : "string", "description" : "The pillarElementIds. The list of pillar elements that are part of the route." } }, "elementDetails" : { "type" : "array", "description" : "The elementDetails. The list of details describing the route schedule.", "items" : { "$ref" : "#/components/schemas/RouteElementDetail" } }, "pillarLatestEffectiveArrivalOffsetMap" : { "type" : "object", "additionalProperties" : { "type" : "integer", "description" : "The pillarLatestEffectiveArrivalOffsetMap. A map of additional time offsets for pillar elements. Each pillar has a latest possible arrival. As a route can consist of multiple pillars, the latest arrival at a certain pillar is also a function of subsequent pillars. This latest arrival may shifted to a later time spot to allow shifitig a pillar around a normal node, even the normal node would fit before the pillar.", "format" : "int64" }, "description" : "The pillarLatestEffectiveArrivalOffsetMap. A map of additional time offsets for pillar elements. Each pillar has a latest possible arrival. As a route can consist of multiple pillars, the latest arrival at a certain pillar is also a function of subsequent pillars. This latest arrival may shifted to a later time spot to allow shifitig a pillar around a normal node, even the normal node would fit before the pillar." }, "flags" : { "type" : "array", "description" : "The flags. A list of flags indicating statii like which source finalized a route.", "items" : { "type" : "string", "description" : "The flags. A list of flags indicating statii like which source finalized a route.", "enum" : [ "FINALIZED_PILLARFORCEARRANGER", "INACTIVE_PILLARFORCEARRANGER", "FINALIZED_ROUTE_FINALIZER", "INACTIVE_ROUTE_FINALIZER" ] } }, "additionalRouteStartOffset" : { "type" : "integer", "description" : "The additionalRouteStartOffset", "format" : "int64" }, "isFinalized" : { "type" : "boolean", "description" : "The isFinalized. Describes if a route was undergoing finalization.", "example" : false }, "isInactive" : { "type" : "boolean", "description" : "The isInactive boolean describes if a route is deactivated.", "example" : false }, "isLockedDown" : { "type" : "boolean", "description" : "The isLockedDown. Describes if a route was undergoing lockdown.", "example" : false } }, "description" : "A single route within the optimization solution. Assigns a resource to a sequence of nodes with full scheduling details. Contains the route header (KPIs), start/end elements and positions, lists of optimizable, non-optimizable, optional, and pillar element ids, per-element scheduling details, and route-level flags." }, "RouteElementDetail" : { "required" : [ "arrivalTime", "departureTime", "durationTime", "elementId", "idleTime", "startTime", "transitionDistance", "transitionTime", "zoneId" ], "type" : "object", "properties" : { "elementId" : { "type" : "string", "description" : "The elementId that the detail item belongs to.", "example" : "Customer-A" }, "startTime" : { "type" : "string", "description" : "The startTime defines the time when a vistior (Resource) starts serving a node.", "format" : "date-time", "example" : "2020-03-06T08:00:00Z" }, "arrivalTime" : { "type" : "string", "description" : "The arrivalTime defines the time when a vistior (Resource) arrives at a node. It is possible that a Visitior needs to idle at the node until a node opens.", "format" : "date-time", "example" : "2020-03-06T07:00:00Z" }, "departureTime" : { "type" : "string", "description" : "The departureTime defines the time a resource is leaving a node.", "format" : "date-time", "example" : "2020-03-06T10:00:00Z" }, "transitionTime" : { "type" : "string", "description" : "The transitionTime gives the time taken for the connection from the previous element to this element.", "format" : "duration", "example" : "PT23M" }, "effectivePosition" : { "$ref" : "#/components/schemas/Position" }, "idleTime" : { "type" : "string", "description" : "The idleTime is the time the Visitor has to wait until a node can be served. By default idle time arrises at the node to be visited. For example, a the arrival time of a Visitor is at 7 in the morning but the node opens at 8. The Visitor has to wait for one hour at the node location until the node can be served.", "format" : "duration", "example" : "PT60M" }, "zoneId" : { "type" : "string", "description" : "The zoneId of detail", "example" : "UTC" }, "whiteSpaceIdleTime" : { "type" : "string", "description" : "The whiteSpaceIdleTime only occurs if the Visitor is using a different reduction time definition for normal nodes and PillarNodes. It is usually introduced to avoid a violation where Pillars are allowed to be served before workingTime and Nodes are not.", "format" : "duration", "example" : "PT26M" }, "durationTime" : { "type" : "string", "description" : "The durationTime defines how long a node is serverd by a Visitor.", "format" : "duration", "example" : "PT120M" }, "transitionDistance" : { "type" : "string", "description" : "The transitionDistance gives the distance taken for the connection from the previous element to this element.", "example" : "100.0 km" }, "choosenWorkingHoursIndex" : { "type" : "integer", "description" : "Each visitor can have a list of workingHours. The choosenWorkingHoursIndex is the index of the Visitors workingHour in which the element is visited.", "format" : "int32", "example" : 1 }, "chosenOpeningHoursIndex" : { "type" : "integer", "description" : "Each node can have a list of openingHours. The chosenOpeningHoursIndex is the index of the node openingHour in which the node is visited.", "format" : "int32", "example" : 1 }, "earlyDeviation" : { "type" : "string", "description" : "The earlyDeviation. The early deviation describes how long before the element opens the Visitor arrives. If the value is negative, the Vistor arrives after the element already opens.", "format" : "duration", "example" : "PT30M" }, "lateDeviation" : { "type" : "string", "description" : "The lateDeviation. The late deviation describes how much lateness the Vistor has. For example, the element to be visited is open from 8-11 and the desired visit duration is 2 hours. The Visitor has to arrive latest by 9 to finish the Job until 11. If the Visitor arrives at 10 the late deviation will be one hour, as the Visitor needs till 12 to finish the Job. The late deviation can be also negative indicating not beeing late. For example if the Visitor reaches the element by 8 and finishes the Job by 10 and the element closes at 11 the late deviation will be -1 hour.", "format" : "duration", "example" : "PT-30M" }, "scheduleStatus" : { "type" : "string", "description" : "The scheduleStatus.", "example" : "INTIME", "enum" : [ "UNKNOWN", "EARLY", "IDLE", "INTIME", "LATE" ] }, "visitorId" : { "type" : "string", "description" : "The visitorId. The id of the Visitor serving the element.", "example" : "Laura" }, "loadChange" : { "type" : "array", "description" : "LEGACY: The change of the load of the element caused by the Visitor. For example, when the element requested 2 items and the Visitor provided only 1 item the loadChange value would be 1.", "items" : { "type" : "number", "description" : "LEGACY: The change of the load of the element caused by the Visitor. For example, when the element requested 2 items and the Visitor provided only 1 item the loadChange value would be 1.", "format" : "double" } }, "curCapacity" : { "type" : "array", "description" : "LEGACY: The curCapacity of the visitor after visiting the element.", "items" : { "type" : "number", "description" : "LEGACY: The curCapacity of the visitor after visiting the element.", "format" : "double" } }, "beforeVisitNodeDepot" : { "$ref" : "#/components/schemas/INodeDepot" }, "afterVisitNodeDepot" : { "$ref" : "#/components/schemas/INodeDepot" }, "nodeViolations" : { "type" : "array", "description" : "The nodeViolations. The violations collected at the element/node. For example, lateViolation, early violation etc.", "items" : { "$ref" : "#/components/schemas/Violation" } }, "isUnlocatedIdleTime" : { "type" : "boolean", "description" : "The isUnlocatedIdleTime changes the representation of the idle time in the solution. By default idle time is located at the node to be waited for. If true, the idle time becomes unlocated. For example, a Visitor can reach a node (that opens at 8) by 7 in the morning. If the idle time is unlocated, the arrival time will be represented as 8 (instead of 7). " } }, "description" : "The full scheduling record for a single node within a route. Extends the minimal timing data with idle time, transit time and distance to the next element, early/late arrival flags, per-node violations, schedule status, white-space (slack) information, and pickup-and-delivery load exchange details. One RouteElementDetail is produced per visited node in each route of the solution." }, "RouteHeader" : { "required" : [ "cost", "distance", "idleTime", "isAlternateDestination", "isClosed", "prodTime", "routeViolations", "termiDistance", "termiTime", "time", "tranTime" ], "type" : "object", "properties" : { "cost" : { "type" : "number", "description" : "The abstract cost value of the route.", "format" : "double", "example" : 2468.32 }, "time" : { "type" : "string", "description" : "The time that is needed for the route.", "format" : "duration", "example" : "PT30M" }, "idleTime" : { "type" : "string", "description" : "The accumlated idleTime of the route.", "format" : "duration", "example" : "PT30M" }, "prodTime" : { "type" : "string", "description" : "The productive time of the route. Productive time is working-time spend at a node.", "format" : "duration", "example" : "PT30M" }, "tranTime" : { "type" : "string", "description" : "The tranTime. The summed transit time of the route.", "format" : "duration", "example" : "PT310M" }, "termiTime" : { "type" : "string", "description" : "The termiTime. The time taken from the last element to the termination element of the route.", "format" : "duration", "example" : "PT800M" }, "distance" : { "type" : "string", "description" : "The distance. The summed transit distance of the route.", "example" : "800.0 km" }, "termiDistance" : { "type" : "string", "description" : "The termiDistance. The distance taken from the last element to the termination element of the route.", "example" : "53.0 km" }, "routeViolations" : { "type" : "array", "description" : "The routeViolations. Violations that occur on route level. For example, overtime, overdistance etc.", "items" : { "$ref" : "#/components/schemas/Violation" } }, "isAlternateDestination" : { "type" : "boolean", "description" : "The isAlternateDestination boolean. Descibes of the Resource has an alternate destination. The Resource has to end it's Route at the alternate destination there but will start from the original route start again the next working hour." }, "isClosed" : { "type" : "boolean", "description" : "The isClosed boolean describes if a Resource has to visit the termination element of the Route. By default, the start element and the termination element of a Route is the Resource itself. In case of a closed route, by default, the Resource returns to its original starting location." } }, "description" : "The header of the solution per route is summarizing important data like number of elements in the route , total time needed for the route etc." }, "RouteTrip" : { "required" : [ "trips" ], "type" : "object", "properties" : { "trips" : { "type" : "array", "description" : "Trips representing the route.", "items" : { "$ref" : "#/components/schemas/ResourceTrip" } } }, "description" : "A container for the sequence of trip segments that make up a route. Each segment is a ResourceTrip with an encoded polyline representing the path between consecutive stops." }, "SameVisitorNodeRelation" : { "required" : [ "typeName" ], "type" : "object", "description" : "A relation requiring that the master node and related nodes are visited by the same resource. Ensures a single resource handles all coupled nodes.", "allOf" : [ { "$ref" : "#/components/schemas/NodeRelationType" }, { "type" : "object", "properties" : { "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "SameVisitor", "default" : "SameVisitor" } } } ] }, "SimpleLoad" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/ILoad" }, { "type" : "object", "properties" : { "loadId" : { "type" : "string" }, "isRequest" : { "type" : "boolean" }, "isFuzzyVisit" : { "type" : "boolean" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "SimpleLoad", "default" : "SimpleLoad" } } } ] }, "SimpleLoadCapacity" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/ILoadCapacity" }, { "type" : "object", "properties" : { "loadCapacityId" : { "type" : "string" }, "maxCapacityValue" : { "type" : "integer", "description" : "The maximum individual load capacity of this depot entry.", "format" : "int32", "example" : 100 }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "SimpleLoadCapacity", "default" : "SimpleLoadCapacity" } } } ] }, "SimpleNodeDepot" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/INodeDepot" }, { "type" : "object", "properties" : { "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "SimpleNodeDepot", "default" : "SimpleNodeDepot" } } } ] }, "SimpleResourceDepot" : { "required" : [ "maximalUnitMatchedCapacity", "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/IResourceDepot" }, { "type" : "object", "properties" : { "maximalUnitMatchedCapacity" : { "type" : "number", "description" : "The maximal unit matched total capacity of the depot.", "format" : "double" }, "capacityUnitMap" : { "type" : "object", "additionalProperties" : { "type" : "number", "description" : "The capacityUnitMap of the depot.", "format" : "double" }, "description" : "The capacityUnitMap of the depot." }, "perKilometerCostFactorMap" : { "type" : "object", "additionalProperties" : { "type" : "integer", "description" : "The perKilometerCostFactorMap of the depot.", "format" : "int32" }, "description" : "The perKilometerCostFactorMap of the depot." }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "SimpleResourceDepot", "default" : "SimpleResourceDepot" }, "emptyAtEndOfRouteFactorMap" : { "type" : "object", "additionalProperties" : { "type" : "integer", "description" : "The emptyAtEndOfRouteFactorMap of the depot.", "format" : "int32" }, "description" : "The emptyAtEndOfRouteFactorMap of the depot." } } } ] }, "Solution" : { "required" : [ "routes" ], "type" : "object", "properties" : { "optimizationStatus" : { "$ref" : "#/components/schemas/OptimizationStatus" }, "id" : { "type" : "string", "description" : "An id created by the system that can be used for unique identification", "example" : "626ba175a9d4fa6d6beec158" }, "createdTimeStamp" : { "type" : "integer", "description" : "A timestamp the Snapshot was created that will automatically filled out, if neccessary", "format" : "int64" }, "creator" : { "type" : "string", "description" : "An id related to the creator that is filled out autmatically", "example" : "11aa65b13c2a6d34f8727e82e403ce869e3bba1d35c45c595e8cc5ce5e74e57a" }, "ident" : { "type" : "string", "description" : "An optional title/ident inhertited from the OptimizationCondig.", "example" : "JOpt-Run-603886271000" }, "header" : { "$ref" : "#/components/schemas/SolutionHeader" }, "routes" : { "type" : "array", "description" : "The routes of the solution.", "items" : { "$ref" : "#/components/schemas/Route" } } }, "description" : "The optimization solution. In a result snapshot, this contains the computed route assignments, scheduling details per node, violation reports, and summary headers (cost, distance, time). When provided as input (warm start), the optimizer uses this solution as its initial starting point and attempts to improve upon it. This enables incremental re-optimization, manual plan adjustments, and 'continue where we left off' workflows. If omitted in the input, the optimizer constructs a solution from scratch using its construction heuristic." }, "SolutionHeader" : { "required" : [ "jobViolations", "numRoutes", "numScheduledRoutes", "totCost", "totDistance", "totElements", "totIdleTime", "totProdTime", "totTermiDistance", "totTermiTime", "totTime", "totTranTime", "unassignedElementIds" ], "type" : "object", "properties" : { "numRoutes" : { "type" : "integer", "description" : "The numRoutes. The number of routes.", "format" : "int32", "example" : 10 }, "numScheduledRoutes" : { "type" : "integer", "description" : "The numScheduledRoutes. The number of routes that have non-zero time.", "format" : "int32", "example" : 8 }, "totElements" : { "type" : "integer", "description" : "The total number of Elements inlucidng Nodes and Resoures", "format" : "int32", "example" : 516 }, "unassignedElementIds" : { "type" : "array", "description" : "The unassignedElementIds, The ids of the elements that were unassigned during the Optimization run. Either by the AutoFilter or at start up due to conflicting hard-constraints.", "items" : { "type" : "string", "description" : "The unassignedElementIds, The ids of the elements that were unassigned during the Optimization run. Either by the AutoFilter or at start up due to conflicting hard-constraints." } }, "totCost" : { "type" : "number", "description" : "The total cost is the abstract value that is used as figure of merit during the Optimization run.", "format" : "double", "example" : 95164.1314 }, "totTime" : { "type" : "string", "description" : "The total time needed for all routes.", "format" : "duration", "example" : "PT480M" }, "totIdleTime" : { "type" : "string", "description" : "The total IdleTime accumulated over all routes.", "format" : "duration", "example" : "PT30M" }, "totProdTime" : { "type" : "string", "description" : "The total Productive Time accumulated over all routes", "format" : "duration", "example" : "PT300M" }, "totTranTime" : { "type" : "string", "description" : "The total transit Time accumulated over all routes", "format" : "duration", "example" : "PT200M" }, "totTermiTime" : { "type" : "string", "description" : "The total termination Time accumulated over all routes", "format" : "duration", "example" : "PT30M" }, "totDistance" : { "type" : "string", "description" : "The total distance accumulated over all routes", "example" : "100.0 km" }, "totTermiDistance" : { "type" : "string", "description" : "The total termiantion distance accumulated over all routes", "example" : "100.0 km" }, "jobViolations" : { "type" : "array", "description" : "The jobViolations. The violation that occured on Job level. This does NOT contain individual node violations like lateness etc. Moreover, it contains violations like relation-constraints between nodes. For example, node 'A' needs to be visited before node 'B' is violated.", "items" : { "$ref" : "#/components/schemas/Violation" } } }, "description" : "The header of the whole solution. Summarizing important data like total number of routes, total time needed for ALL routes etc." }, "StartReductionTimeDefinition" : { "required" : [ "isReductionTimeOnlyUsedForDriving", "maxRouteStartReductionTime" ], "type" : "object", "properties" : { "maxRouteStartReductionTime" : { "type" : "string", "description" : "The maximal Routes' Start Reduction Time for nodes the Optimizer is allowed to use.", "format" : "duration", "example" : "PT30M" }, "isReductionTimeOnlyUsedForDriving" : { "type" : "boolean", "description" : "The boolean isReductionTimeOnlyUsedForDriving defines if a Resource is allowed to use reduction time only for driving to the first node but not for working on it." } }, "description" : "The settings/definition for the reduction time at the start of the route for non-pillar nodes. A reduction time allows the Resource to start working/driving before the actual official workingHours start. For example, a customer node opens at 8 in the morning and the resource needs 25 minutes to drive to the node. The official workingHour of the Resource start at 8 as well. By giving a maximal reduction time of, for example, one hour and only allow the reduction time to be used for driving, the Resource will start 25 minutes to earlier to reach the node by 8." }, "StartReductionTimeIncludeDefinition" : { "required" : [ "isReductionTimeIncludedInWorkingTime" ], "type" : "object", "properties" : { "isReductionTimeIncludedInWorkingTime" : { "type" : "boolean", "description" : "The boolean isReductionTimeIncludedInWorkingTime. If reduction time is used it can be either counted as part of the working time or not." } }, "description" : "The settings/defintion for how to handle working time in the context of reduction time." }, "StartReductionTimePillarDefinition" : { "required" : [ "isReductionTimeOnlyUsedForDrivingPillar", "maxRouteStartReductionTimePillar" ], "type" : "object", "properties" : { "maxRouteStartReductionTimePillar" : { "type" : "string", "description" : "The maximal Routes' Start Reduction Time for pillars nodes the Optimizer is allowed to use.", "format" : "duration", "example" : "PT30M" }, "isReductionTimeOnlyUsedForDrivingPillar" : { "type" : "boolean", "description" : "The boolean isReductionTimeOnlyUsedForDriving defines if a Resource is allowed to use reduction time only for driving to the first node (here a pillar) but not for working on it." } }, "description" : "The settings/defintion for the reduction time at the start of the route for pillar nodes. Please see startReductionTimeDefinition for details." }, "StayOutCycleDefinition" : { "required" : [ "cycleLength", "cycleStart" ], "type" : "object", "properties" : { "cycleLength" : { "type" : "string", "description" : "The length of one stay-out evaluation cycle, expressed as an ISO 8601 duration (e.g. 'PT7D' for one week).", "format" : "duration", "example" : "PT7D" }, "cycleStart" : { "type" : "string", "description" : "The start date of the first stay-out evaluation cycle. Subsequent cycles begin at cycleStart + N * cycleLength.", "format" : "date" } }, "description" : "Defines the repeating cycle within which stay-out limits are evaluated. For example, a 7-day cycle starting on a specific date allows the optimizer to count stay-outs per week and enforce weekly limits." }, "StayOutDefinition" : { "required" : [ "maxStaysOutInRow", "maxTotalStaysOut", "minRecovery" ], "type" : "object", "properties" : { "maxTotalStaysOut" : { "type" : "integer", "description" : "The maximum total number of overnight stays the resource may have across all working-hour cycles.", "format" : "int32" }, "maxStaysOutInRow" : { "type" : "integer", "description" : "The maximum number of consecutive overnight stays in a row before the resource must return home or observe a recovery period.", "format" : "int32" }, "minRecovery" : { "type" : "string", "description" : "The minimum recovery duration the resource must spend at its home location before another stay-out sequence is permitted. Expressed as an ISO 8601 duration (e.g. 'PT24H' for one full day).", "format" : "duration", "example" : "PT1D" } }, "description" : "Defines overnight-stay policies for this resource, including the maximum total number of stay-outs permitted, the maximum consecutive stay-outs in a row, and the minimum recovery period between stay-out sequences. Used in multi-day planning scenarios where resources may stay overnight near their last stop." }, "StreamPersistenceStrategySetting" : { "required" : [ "saveError", "saveProgress", "saveStatus", "saveWarning" ], "type" : "object", "properties" : { "saveProgress" : { "type" : "boolean", "description" : "The saveProgress" }, "cycleProgress" : { "type" : "boolean", "description" : "Cycle progress. Only takes action if saveProgress is true.", "example" : true }, "saveStatus" : { "type" : "boolean", "description" : "The saveStatus" }, "cycleStatus" : { "type" : "boolean", "description" : "Cycle status. Only takes action if saveStatus is true.", "example" : true }, "saveWarning" : { "type" : "boolean", "description" : "The saveWarning", "example" : true }, "saveError" : { "type" : "boolean", "description" : "The saveError", "example" : true } }, "description" : "The streamPersistenceStratgySetting" }, "StringIntegerPair" : { "required" : [ "left", "right" ], "type" : "object", "properties" : { "left" : { "type" : "string", "description" : "A string key, typically a node or element identifier." }, "right" : { "type" : "integer", "description" : "An integer value associated with the key (e.g. a count, index, or capacity value).", "format" : "int32" } }, "description" : "A list of key-value pairs mapping element identifiers to integer values. Used internally to mirror multi-route constraint configurations across working hours." }, "SupplyFlexLoad" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/ILoad" }, { "type" : "object", "properties" : { "loadId" : { "type" : "string" }, "isRequest" : { "type" : "boolean" }, "isFuzzyVisit" : { "type" : "boolean" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "SupplyFlexLoad", "default" : "SupplyFlexLoad" } } } ] }, "TextSolution" : { "required" : [ "textSolution" ], "type" : "object", "properties" : { "textSolution" : { "type" : "string", "description" : "The textSolution" } }, "description" : "The textSolution" }, "TimeComparisonJuncture" : { "required" : [ "isMasterNodeWorkingStart", "isRelatedNodeWorkingStart" ], "type" : "object", "properties" : { "isMasterNodeWorkingStart" : { "type" : "boolean", "description" : "Defines if the master nodes start is used as comparison point (true). If false, the end of the master node will be used." }, "isRelatedNodeWorkingStart" : { "type" : "boolean", "description" : "Defines if the related nodes start is used as comparison point (true). If false, the end of the related node will be used." } }, "description" : "The timeComparisonJuncture of the relation." }, "TimeWindowNodeRelation" : { "required" : [ "maxTimeDeviation", "minTimeDeviation", "typeName" ], "type" : "object", "description" : "A time-window relation that enforces temporal precedence between a master node and related nodes. The related node must be visited within [minTimeDeviation, maxTimeDeviation] of the master node's visit. The timeComparisonJuncture controls whether start or end times are compared.", "allOf" : [ { "$ref" : "#/components/schemas/NodeRelationType" }, { "type" : "object", "properties" : { "minTimeDeviation" : { "type" : "string", "description" : "The minTimeDeviation defines the minimal time of the relation.", "format" : "duration", "example" : "PT10M" }, "maxTimeDeviation" : { "type" : "string", "description" : "The maxTimeDeviation defines the minimal time of the relation.", "format" : "duration", "example" : "PT1H" }, "timeComparisonJuncture" : { "$ref" : "#/components/schemas/TimeComparisonJuncture" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "TimeWindow", "default" : "TimeWindow" } } } ] }, "TypeConstraint" : { "required" : [ "typeName", "typeNames" ], "type" : "object", "description" : "A string-based skill constraint on a node. The node requires resources whose TypeQualification includes at least one matching type name. Unmatched assignments produce violations.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "typeNames" : { "type" : "array", "description" : "A list of user-provided type-names. A Constraint type name must match to a Qualification type name to result in a violation free solution.", "items" : { "type" : "string", "description" : "A list of user-provided type-names. A Constraint type name must match to a Qualification type name to result in a violation free solution." } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "Type", "default" : "Type" } } } ] }, "TypeDictionaries" : { "type" : "object", "properties" : { "typeDictionaries" : { "type" : "array", "description" : "The optional list of typeDictionaries", "items" : { "$ref" : "#/components/schemas/TypeDictionary" } } }, "description" : "Optional lookup dictionaries that map integer-based type identifiers to human-readable type names. Used in conjunction with BitType qualifications and constraints to translate compact bitset representations into meaningful skill or category labels for reporting and debugging purposes." }, "TypeDictionary" : { "required" : [ "mapping", "typeNames" ], "type" : "object", "properties" : { "mapping" : { "type" : "object", "additionalProperties" : { "type" : "string", "description" : "The mapping of a certain type. or multiple types" }, "description" : "The mapping of a certain type. or multiple types" }, "typeNames" : { "type" : "array", "description" : "List of type names this dictionary applies to.", "items" : { "type" : "string", "description" : "List of type names this dictionary applies to." } } }, "description" : "The optional list of typeDictionaries" }, "TypeLevelOffering" : { "required" : [ "level" ], "type" : "object", "properties" : { "level" : { "type" : "integer", "description" : "The expertise level", "format" : "int32" } }, "description" : "Specifies the expertise level a resource offers for a given skill type. Matched against TypeLevelRequirement on the node side to determine constraint satisfaction and cost penalties." }, "TypeLevelRequirement" : { "required" : [ "isMin", "level" ], "type" : "object", "properties" : { "level" : { "type" : "integer", "description" : "The expertise level", "format" : "int32" }, "isMin" : { "type" : "boolean", "description" : "The boolean isMin. If isMin==true, the level is a minimal level that needs to be fulfilled." } }, "description" : "Specifies the expertise level a node requires for a given skill type. The isMin flag controls whether the level is a minimum threshold (resource must meet or exceed) or an exact match requirement." }, "TypeQualification" : { "required" : [ "typeName", "typeNames" ], "type" : "object", "description" : "A string-based skill qualification. Declares a list of type names that the resource can fulfill. Matched against TypeConstraint on nodes — a match means the resource has the required skill.", "allOf" : [ { "$ref" : "#/components/schemas/QualificationType" }, { "type" : "object", "properties" : { "typeNames" : { "type" : "array", "description" : "A list of user-provided type-names. A Constraint type name must match to a Qualification type name to result in a violation free solution.", "items" : { "type" : "string", "description" : "A list of user-provided type-names. A Constraint type name must match to a Qualification type name to result in a violation free solution." } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "Type", "default" : "Type" } } } ] }, "TypeWithExpertise" : { "required" : [ "isMin", "level", "type" ], "type" : "object", "properties" : { "type" : { "type" : "string", "description" : "The type name that in addition requires a certain expertise level." }, "level" : { "type" : "number", "description" : "The expertise level", "format" : "double" }, "isMin" : { "type" : "boolean", "description" : "The boolean isMin. If isMin==true, the level is a minimal level that needs to be fulfilled." } }, "description" : "A skill type paired with an expertise level. Used in TypeWithExpertiseQualification and TypeWithExpertiseConstraint to model graded skills (e.g. 'Electrician Level 3')." }, "TypeWithExpertiseConstraint" : { "required" : [ "typeName", "typesWithExpertise" ], "type" : "object", "description" : "A string-based skill constraint with expertise levels on a node. Requires resources whose TypeWithExpertiseQualification matches both the type name and meets the minimum expertise level. Supports cost models for penalizing over- or under-qualified assignments.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "typesWithExpertise" : { "type" : "array", "description" : "The types with expertise", "items" : { "$ref" : "#/components/schemas/TypeWithExpertise" } }, "costModel" : { "type" : "string", "description" : "The cost model for matching the expertise.", "enum" : [ "PENALIZE_MATCHING_SKILL_HIGH_DELTA", "PENALIZE_MATCHING_SKILL_LOW_DELTA", "NO_PENALIZE_MATCHING_SKILL" ] }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "TypeWithExpertise", "default" : "TypeWithExpertise" } } } ] }, "TypeWithExpertiseQualification" : { "required" : [ "typeName", "typesWithExpertise" ], "type" : "object", "description" : "A string-based skill qualification with expertise levels. Declares a list of type-name/expertise pairs that the resource offers. Matched against TypeWithExpertiseConstraint on nodes to verify both skill presence and required expertise thresholds.", "allOf" : [ { "$ref" : "#/components/schemas/QualificationType" }, { "type" : "object", "properties" : { "typesWithExpertise" : { "type" : "array", "description" : "A list of user-provided type-names and expertise levels. A Constraint type-name with its required expertise must be fulfill by the type-with-expertise Qualification to result in a violation free solution.", "items" : { "$ref" : "#/components/schemas/TypeWithExpertise" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "TypeWithExpertise", "default" : "TypeWithExpertise" } } } ] }, "UKPostCode" : { "required" : [ "areaIdent", "typeName" ], "type" : "object", "description" : "A UK postcode zone code with hierarchical components: area identifier (e.g. 'SW'), optional district number, optional sector number, and optional unit identifier. Used for UK-specific territory partitioning in zone-based routing constraints.", "allOf" : [ { "$ref" : "#/components/schemas/ZoneCodeType" }, { "type" : "object", "properties" : { "areaIdent" : { "type" : "string", "description" : "The area identifier of the UK postcode (e.g. 'SW', 'EC', 'M'). This is the outward code's letter prefix that identifies the postal area." }, "districtIdentOpt" : { "type" : "integer", "description" : "The optional district number within the postal area (e.g. 1 in 'SW1').", "format" : "int32" }, "sectorIdentOpt" : { "type" : "integer", "description" : "The optional sector number from the inward code (e.g. 4 in 'SW1A 4').", "format" : "int32" }, "unitIdentOpt" : { "type" : "string", "description" : "The optional unit identifier from the inward code (e.g. 'AA' in 'SW1A 4AA')." }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "UKPostCode", "default" : "UKPostCode" } } } ] }, "UKPostCodeConstraint" : { "required" : [ "typeName", "zoneCodes" ], "type" : "object", "description" : "A node constraint requiring the visiting resource to hold a UKPostCodeQualification covering this node's UK postcode territory. Unmatched assignments produce violations.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "zoneCodes" : { "type" : "array", "description" : "The list of UK postcode zone codes that a resource must be qualified for to visit this node.", "items" : { "$ref" : "#/components/schemas/ZoneCodeType" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "UKPostCodeConstraint", "default" : "UKPostCodeConstraint" } } } ] }, "UKPostCodeQualification" : { "required" : [ "myCode", "typeName" ], "type" : "object", "description" : "A resource qualification declaring which UK postcode territories the resource is authorized to operate in. Matched against UKPostCodeConstraint on nodes to ensure postal-district compliance.", "allOf" : [ { "$ref" : "#/components/schemas/QualificationType" }, { "type" : "object", "properties" : { "myCode" : { "$ref" : "#/components/schemas/ZoneCodeType" }, "myExtraCodes" : { "type" : "array", "description" : "Additional UK postcodes this resource is also qualified to serve, beyond the primary code.", "items" : { "$ref" : "#/components/schemas/ZoneCodeType" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "UKPostCodeQualification", "default" : "UKPostCodeQualification" } } } ] }, "UnloadAllLoad" : { "required" : [ "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/ILoad" }, { "type" : "object", "properties" : { "loadId" : { "type" : "string" }, "isRequest" : { "type" : "boolean" }, "isFuzzyVisit" : { "type" : "boolean" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "UnloadAllLoad", "default" : "UnloadAllLoad" } } } ] }, "Violation" : { "required" : [ "attribute", "category", "code", "desc", "subAttribute", "value" ], "type" : "object", "properties" : { "value" : { "type" : "string", "description" : "If for example a constraint is triggering the violation, the underlying ident of the constraint class might be provided." }, "desc" : { "type" : "string", "description" : "The description of the violation. A human readable description of the violation", "example" : "Late time [min]: 507.98525" }, "offender" : { "type" : "string", "description" : "The offender corresponding to the violation. That could be a node or route id.", "example" : "Node_0" }, "category" : { "type" : "string", "description" : "The category of the violation. The main category of the violation.", "example" : "CONSTRAINTVIOLATION" }, "attribute" : { "type" : "string", "description" : "The attribute is further defining the type of the violation. For example, late and early violation belong to the attribute 'TIMECONSTRAINT'.", "example" : "TIMECONSTRAINT" }, "subAttribute" : { "type" : "string", "description" : "The subAttribute defines what kind of violation we are dealing with.", "example" : "LATE" }, "code" : { "type" : "integer", "description" : "The code is the unique code for each Violation type.", "format" : "int32", "example" : 5 } }, "description" : "A single constraint violation detected during optimization. Describes the violation value (e.g. minutes of lateness), a human-readable description, the offending element (node or route), and a category/attribute/subAttribute taxonomy for programmatic filtering (e.g. CONSTRAINTVIOLATION > TIMECONSTRAINT > LATE)." }, "WeekDay" : { "type" : "object", "description" : "Matches a specific day of the week (1 = Monday … 7 = Sunday, ISO-8601).", "allOf" : [ { "$ref" : "#/components/schemas/DateDef" }, { "type" : "object", "properties" : { "day" : { "maximum" : 7, "minimum" : 1, "type" : "integer", "description" : "ISO-8601 day of the week (1 = Monday, 7 = Sunday).", "format" : "int32", "example" : 1 } } } ] }, "WorkingHours" : { "required" : [ "begin", "end", "zoneId" ], "type" : "object", "properties" : { "begin" : { "type" : "string", "description" : "The begin of the Working hours.", "format" : "date-time", "example" : "2020-03-06T07:00:00Z" }, "end" : { "type" : "string", "description" : "The end of the Working hours.", "format" : "date-time", "example" : "2020-03-06T17:00:00Z" }, "zoneId" : { "type" : "string", "description" : "The zoneId of the Working hours.", "example" : "UTC" }, "maxTime" : { "type" : "string", "description" : "The maximal time a Resource should work within the WorkingHour.", "format" : "duration", "example" : "PT480M" }, "maxDistance" : { "type" : "string", "description" : "The maximla distance a resource should cover within the WorkingHour.", "example" : "800.0 km" }, "stayOutCycleDefinition" : { "$ref" : "#/components/schemas/StayOutCycleDefinition" }, "startReductionTimeDefinition" : { "$ref" : "#/components/schemas/StartReductionTimeDefinition" }, "startReductionTimePillarDefinition" : { "$ref" : "#/components/schemas/StartReductionTimePillarDefinition" }, "startReductionTimeIncludeDefinition" : { "$ref" : "#/components/schemas/StartReductionTimeIncludeDefinition" }, "localFlexTime" : { "type" : "string", "description" : "The local flexible time. In some cases a Resource should start working later compared to what is defined in the working hours. This way idle time can be reduced. The local flex time is the maximum a Resource is allowed to start working later, depending on the Optimization maybe flex time is not or only partially used.", "format" : "duration", "example" : "PT30M" }, "localPostFlexTime" : { "type" : "string", "description" : "The maximum duration by which the resource is allowed to end work earlier than the working-hour boundary. Acts as a flexible end-of-shift buffer — if the last node finishes ahead of schedule, the resource may clock off early by up to this amount, reducing unnecessary idle time at the end of the route. See also localPostFlexTimeOnlyOnOvertime to restrict this behavior to overtime-reduction scenarios only.", "format" : "duration", "example" : "PT30M" }, "localPostFlexTimeOnlyOnOvertime" : { "type" : "boolean", "description" : "The post flextime is only applied to reduce overtime.", "nullable" : true, "default" : false }, "maxLocalPillarAfterHoursTime" : { "type" : "string", "description" : "The maximum duration a pillar node is allowed to be served after the official working-hours end for this specific working-hour window. Enables late-shift mandatory stops (e.g. end-of-day depot return) that extend slightly beyond the defined working-hour boundary.", "format" : "duration", "example" : "PT30M" }, "nodeColorCapacities" : { "type" : "array", "description" : "Per-color capacity limits for routes produced from this working hour. Controls the composition of the route by limiting how many nodes of a given color category may appear (e.g. at most 40% hazardous-goods stops). Overrides any resource-level color capacity when set at the working-hour level.", "items" : { "$ref" : "#/components/schemas/NodeColorCapacity" } }, "workingHoursConstraints" : { "type" : "array", "description" : "The constraints for this working hour.", "items" : { "$ref" : "#/components/schemas/Constraint" } }, "multiWorkingHoursConstraints" : { "type" : "array", "description" : "Constraints that span across multiple working hours of the same resource. Unlike workingHoursConstraints (which apply to a single working-hour window), these constraints enforce policies across the full planning horizon — for example, limiting the total number of a certain node type visited across all days.", "items" : { "$ref" : "#/components/schemas/Constraint" } }, "constructionHooks" : { "type" : "array", "description" : "The hooks for this working hour.", "items" : { "$ref" : "#/components/schemas/ConstructionHook" } }, "qualifications" : { "type" : "array", "description" : "The qualification of the Resource for this working hour. For example, the Resource is allowed to visit a node needing a skill (defined via a constraint) and the Resource is providing this skill.", "items" : { "$ref" : "#/components/schemas/Qualification" } }, "routeStartTimeHook" : { "type" : "string", "description" : "An optional time offset applied to the route start. Shifts the effective departure time from the resource's home location, for example to account for vehicle preparation, warm-up, or loading time before the first stop.", "format" : "duration", "example" : "PT30M" }, "hookElementConnections" : { "type" : "array", "description" : "Pre-computed connections used exclusively during the construction hook phase. These connections override the default element connections for hook-related routing decisions, allowing special distance/time calculations during construction (e.g. depot-to-first-stop distances that differ from normal driving).", "items" : { "$ref" : "#/components/schemas/ReducedNodeEdgeConnectorItem" } }, "isLocalServiceHub" : { "type" : "boolean", "description" : "If true, this resource operates in service-hub mode during this working hour: instead of the resource traveling to visit nodes, nodes are conceptually 'brought to' the resource's location. Useful for modeling stationary service points, reception desks, or warehouse processing stations.", "nullable" : true, "default" : false }, "isAvailableForStay" : { "type" : "boolean", "description" : "The boolean isAvailableForStay defines if this working hour is allowed to end at an overnight stay.", "nullable" : true, "default" : false }, "isClosedRoute" : { "type" : "boolean", "description" : "The isClosedRoute boolean describes if a Resource has to visit the termination element of the Route. By default, the start element and the termination element of a Route is the Resource itself. In case of a closed route, by default, the Resource returns to its original starting location.", "nullable" : true, "default" : true } }, "description" : "A time window during which a resource is available for work. Defined by a begin and end instant with a time zone. Supports maximum working time and distance constraints, overtime/overdistance allowances, start-reduction-time (flex-time) policies, stay-out (overnight) definitions, node color capacities, and optional qualifications and depot configurations per working-hour window." }, "ZoneCodeType" : { "required" : [ "typeName" ], "type" : "object", "properties" : { "typeName" : { "type" : "string" } }, "description" : "A geographic zone identifier attached to nodes and resources for territory-based routing. Subtypes include numeric zone codes (for general territory partitioning) and UK post codes (for UK-specific postal district matching).", "discriminator" : { "propertyName" : "typeName", "mapping" : { "ZoneNumber" : "#/components/schemas/ZoneNumber", "UKPostCode" : "#/components/schemas/UKPostCode" } } }, "ZoneConnection" : { "required" : [ "fromZoneId", "toZoneId" ], "type" : "object", "properties" : { "fromZoneId" : { "type" : "string", "description" : "The zone that is left.", "example" : "1" }, "toZoneId" : { "type" : "string", "description" : "The zone that is entered.", "example" : "2" }, "crossingPenaltyMultiplier" : { "type" : "number", "description" : "The crossingPenaltyMultiplier when going fromZoneId to toZoneId", "format" : "double" } }, "description" : "Zone connections define penalties or restrictions for crossing geographic zone boundaries (e.g. bridge tolls, tunnel crossings, or administrative borders). Each ZoneConnection specifies a pair of zone numbers and an associated crossing cost. When a route transitions between zones, the optimizer accumulates these costs, which discourages unnecessary zone crossings and promotes geographically cohesive routes." }, "ZoneNumber" : { "required" : [ "typeName", "zoneNumber" ], "type" : "object", "description" : "A numeric zone code assigned to nodes and resources for territory-based routing. Zone numbers define geographic partitions and are used with ZoneConnections to penalize or restrict zone crossings.", "allOf" : [ { "$ref" : "#/components/schemas/ZoneCodeType" }, { "type" : "object", "properties" : { "zoneNumber" : { "type" : "integer", "description" : "The numeric zone identifier assigned to this element. Zone numbers are used to define geographic territories for resources and to penalize or restrict zone crossings between nodes via ZoneConnections.", "format" : "int32" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "ZoneNumber", "default" : "ZoneNumber" } } } ] }, "ZoneNumberConstraint" : { "required" : [ "typeName", "zoneCodes" ], "type" : "object", "description" : "A node constraint requiring the visiting resource to hold a ZoneNumberQualification covering this node's zone number. Unmatched assignments produce violations.", "allOf" : [ { "$ref" : "#/components/schemas/ConstraintType" }, { "type" : "object", "properties" : { "zoneCodes" : { "type" : "array", "description" : "The list of numeric zone codes that a resource must be qualified for to visit this node. Used in conjunction with ZoneNumberQualification on the resource side.", "items" : { "$ref" : "#/components/schemas/ZoneCodeType" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "ZoneNumberConstraint", "default" : "ZoneNumberConstraint" } } } ] }, "ZoneNumberQualification" : { "required" : [ "typeName" ], "type" : "object", "description" : "A resource qualification declaring which numeric zone territories the resource is authorized to operate in. Matched against ZoneNumberConstraint on nodes to enforce territory assignments.", "allOf" : [ { "$ref" : "#/components/schemas/QualificationType" }, { "type" : "object", "properties" : { "myCode" : { "$ref" : "#/components/schemas/ZoneCodeType" }, "myExtraCodes" : { "type" : "array", "description" : "Additional zone codes this resource is also qualified to serve, beyond the primary code.", "items" : { "$ref" : "#/components/schemas/ZoneCodeType" } }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "ZoneNumberQualification", "default" : "ZoneNumberQualification" } } } ] }, "d" : { "required" : [ "drivenDistance", "drivenTime", "invocationPosition", "isActive", "onlyApplyOnce", "prioritizeNodeConnectorOnFallbackSpeed", "typeName" ], "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/HookType" }, { "type" : "object", "properties" : { "isActive" : { "type" : "boolean", "description" : "Is the hook active?" }, "prioritizeNodeConnectorOnFallbackSpeed" : { "type" : "boolean", "description" : "In case the route to be used to calculate the average speed is empty, we need to calculate a fallback speed. By default we take the average speed provided by the resource. However, we can also extract a few connections from node connector that belong to the visiting resource of the route and calculated an average speed." }, "onlyApplyOnce" : { "type" : "boolean", "description" : "If only applied once, the hook is autmatically set to be inactive after one execution." }, "invocationPosition" : { "type" : "string", "description" : "When is the hook incorporated?", "enum" : [ "PRE_CONSTRUCTION", "BEFORE_LEFTOVER_HANDLING", "POST_CONSTRUCTION" ] }, "drivenTime" : { "type" : "string", "description" : "The offset for driven time. This time will be transformed into a distance (utilizing average resource speed) that is substracted from the defined maxdistance.", "format" : "duration", "example" : "PT120M" }, "drivenDistance" : { "type" : "string", "description" : "The offset for driven distance. This value is substracted from the defined maxdistance.", "example" : "100.0 km" }, "typeName" : { "type" : "string", "description" : "The typeName of the object", "example" : "MaxDistanceConstructionHook", "default" : "MaxDistanceConstructionHook" } } } ] }, "RunAcceptedResponse" : { "type" : "object", "properties" : { "runId" : { "type" : "string", "description" : "Unique identifier for this run. Use with GET /api/v1/runs/{runId}/result to retrieve the result and GET /api/v1/runs/{runId}/stream/* for live events.", "example" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "submittedAt" : { "type" : "integer", "description" : "Epoch-millisecond timestamp when the run was accepted.", "format" : "int64", "example" : 1775130148792 }, "ident" : { "type" : "string", "description" : "User-defined label echoed back from the input ident field.", "example" : "my-optimization-run" } }, "description" : "Confirmation that a synchronous optimization run has been accepted and started. Use the runId to retrieve the result, subscribe to event streams, or stop the run early." }, "JOptOptimizationWarning" : { "required" : [ "code", "desc", "ident", "jobId", "message", "tenantId" ], "type" : "object", "properties" : { "creator" : { "type" : "string", "description" : "An id related to the creator that is filled out autmatically", "example" : "11aa65b13c2a6d34f8727e82e403ce869e3bba1d35c45c595e8cc5ce5e74e57a" }, "jobId" : { "type" : "string", "description" : "The jobId id. Will be filled out by the optimizer, if necessary", "example" : "UNIQUE_JOB_ID" }, "tenantId" : { "type" : "string", "description" : "The tenant id of the creator started this job.", "example" : "UNIQUE_TENANT_ID" }, "ident" : { "type" : "string", "description" : "The ident of the currently running optimization", "example" : "My-JOpt-Run" }, "message" : { "type" : "string", "description" : "The info message", "example" : "Info about something" }, "code" : { "type" : "integer", "description" : "The info message code", "format" : "int32", "example" : 555 }, "desc" : { "type" : "string", "description" : "The description of the info", "example" : "Info desc" }, "expireAt" : { "type" : "string", "description" : "Optional value that will be used for database cleanup purposes.", "format" : "date-time" } }, "description" : "JOptOptimizationWarning model for the documentation" }, "JOptOptimizationStatus" : { "required" : [ "code", "desc", "ident", "jobId", "message", "tenantId" ], "type" : "object", "properties" : { "creator" : { "type" : "string", "description" : "An id related to the creator that is filled out autmatically", "example" : "11aa65b13c2a6d34f8727e82e403ce869e3bba1d35c45c595e8cc5ce5e74e57a" }, "jobId" : { "type" : "string", "description" : "The jobId id. Will be filled out by the optimizer, if necessary", "example" : "UNIQUE_JOB_ID" }, "tenantId" : { "type" : "string", "description" : "The tenant id of the creator started this job.", "example" : "UNIQUE_TENANT_ID" }, "ident" : { "type" : "string", "description" : "The ident of the currently running optimization", "example" : "My-JOpt-Run" }, "message" : { "type" : "string", "description" : "The info message", "example" : "Info about something" }, "code" : { "type" : "integer", "description" : "The info message code", "format" : "int32", "example" : 555 }, "desc" : { "type" : "string", "description" : "The description of the info", "example" : "Info desc" }, "expireAt" : { "type" : "string", "description" : "Optional value that will be used for database cleanup purposes.", "format" : "date-time" }, "id" : { "type" : "string", "description" : "The obejct id. Will be filled out by the optimizer, if necessary", "example" : "626d49ae5cf422297561c458" } }, "description" : "JOptOptimizationStatus model for the documentation" }, "JOptOptimizationProgress" : { "required" : [ "callerId", "curCost", "curProgress", "desc", "ident", "jobId", "stage", "tenantId" ], "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "The obejct id. Will be filled out by the optimizer, if necessary", "example" : "626d49ae5cf422297561c458" }, "jobId" : { "type" : "string", "description" : "The jobId id. Will be filled out by the optimizer, if necessary", "example" : "UNIQUE_JOB_ID" }, "tenantId" : { "type" : "string", "description" : "The tenant id of the creator started this job.", "example" : "UNIQUE_TENANT_ID" }, "creator" : { "type" : "string", "description" : "An id related to the creator that is filled out autmatically", "example" : "11aa65b13c2a6d34f8727e82e403ce869e3bba1d35c45c595e8cc5ce5e74e57a" }, "ident" : { "type" : "string", "description" : "The ident of the currently running optimization", "example" : "My-JOpt-Run" }, "callerId" : { "type" : "string", "description" : "The id of the currently running optimization algorithm", "example" : "GeneticEvolution" }, "curProgress" : { "type" : "number", "description" : "The progress in percentage of the currently running optimization algorithm", "format" : "double", "example" : 89.0 }, "curCost" : { "type" : "number", "description" : "The current cost of the currently running optimization algorithm", "format" : "double", "example" : 1100.0 }, "stage" : { "type" : "integer", "description" : "The stage of the optimization. The first running algorithm will get the stage 0.", "format" : "int32", "example" : 0 }, "desc" : { "type" : "string", "description" : "The progress as human readable description", "example" : "PC 89.0, RE 1, AL GeneticEvolution, JC 4258.106994896875, RC 4, EC 10, TC 14, TT[h] 24, TU[%] 13, TD[km] 1647.29" }, "expireAt" : { "type" : "string", "description" : "Optional value that will be used for database cleanup purposes.", "format" : "date-time" } }, "description" : "JOptOptimizationProgress model for the documentation" }, "JOptOptimizationError" : { "required" : [ "code", "desc", "ident", "jobId", "message", "tenantId" ], "type" : "object", "properties" : { "creator" : { "type" : "string", "description" : "An id related to the creator that is filled out autmatically", "example" : "11aa65b13c2a6d34f8727e82e403ce869e3bba1d35c45c595e8cc5ce5e74e57a" }, "jobId" : { "type" : "string", "description" : "The jobId id. Will be filled out by the optimizer, if necessary", "example" : "UNIQUE_JOB_ID" }, "tenantId" : { "type" : "string", "description" : "The tenant id of the creator started this job.", "example" : "UNIQUE_TENANT_ID" }, "ident" : { "type" : "string", "description" : "The ident of the currently running optimization", "example" : "My-JOpt-Run" }, "message" : { "type" : "string", "description" : "The info message", "example" : "Info about something" }, "code" : { "type" : "integer", "description" : "The info message code", "format" : "int32", "example" : 555 }, "desc" : { "type" : "string", "description" : "The description of the info", "example" : "Info desc" }, "expireAt" : { "type" : "string", "description" : "Optional value that will be used for database cleanup purposes.", "format" : "date-time" } }, "description" : "JOptOptimizationError model for the documentation" }, "Status" : { "type" : "object", "properties" : { "description" : { "type" : "string" }, "status" : { "type" : "string" } } } }, "securitySchemes" : { "TenantId" : { "type" : "apiKey", "description" : "Tenant identifier scoping all persisted data. In SaaS deployments this header is injected by the API gateway. In on-premise and local Docker deployments any fixed value is acceptable (e.g. 'local' or 'my-tenant').", "name" : "X-Tenant-Id", "in" : "header" } } } }