Input/output schema

Input

The format for timestamps should be RFC3339, e.g.: "2023-01-01T00:00:00Z".

The input schema is a JSON payload defining the available workers and the required demand to satisfy for a shift scheduling problem. Nextmv's tools are designed to operate directly on business data (in JSON) to produce decisions that are actionable by software systems. This makes decisions more interpretable and easier to test. It also makes integration with data warehouses and business intelligence platforms significantly easier. An input contains the following components:

Field name	Required	Data type	SI Unit	Description	Example
`workers`	Yes	`array` of `worker`	NA	Workers to assign.	See `worker`
`required_workers`	Yes	`array` of `required worker`	NA	A predicted need of workers at certain times.	See `required worker`

Here you can find a sample .json with the input schema:

JSON

{
  "workers": [
    {
      "availability": [
        {
          "start": "2023-09-03T04:00:00+02:00",
          "end": "2023-09-03T11:00:00+02:00"
        },
        {
          "start": "2023-09-04T14:00:00+02:00",
          "end": "2023-09-04T22:00:00+02:00"
        }
      ],
      "id": "1"
    },
    {
      "availability": [
        {
          "start": "2023-08-28T15:00:00+02:00",
          "end": "2023-08-29T00:00:00+02:00"
        },
        {
          "start": "2023-08-29T16:00:00+02:00",
          "end": "2023-08-29T17:00:00+02:00"
        }
      ],
      "id": "2"
    },
    {
      "availability": [
        {
          "start": "2023-08-29T02:00:00+02:00",
          "end": "2023-08-29T11:00:00+02:00"
        },
        {
          "start": "2023-08-30T16:00:00+02:00",
          "end": "2023-08-31T03:00:00+02:00"
        },
        {
          "start": "2023-08-31T15:00:00+02:00",
          "end": "2023-08-31T22:00:00+02:00"
        },
        {
          "start": "2023-09-01T07:00:00+02:00",
          "end": "2023-09-01T12:00:00+02:00"
        },
        {
          "start": "2023-09-01T23:00:00+02:00",
          "end": "2023-09-02T05:00:00+02:00"
        },
        {
          "start": "2023-09-02T03:00:00+02:00",
          "end": "2023-09-02T08:00:00+02:00"
        },
        {
          "start": "2023-09-03T07:00:00+02:00",
          "end": "2023-09-03T11:00:00+02:00"
        }
      ],
      "id": "3"
    },
    {
      "availability": [
        {
          "start": "2023-08-28T11:00:00+02:00",
          "end": "2023-08-28T19:00:00+02:00"
        },
        {
          "start": "2023-08-28T20:00:00+02:00",
          "end": "2023-08-29T03:00:00+02:00"
        },
        {
          "start": "2023-08-29T04:00:00+02:00",
          "end": "2023-08-29T06:00:00+02:00"
        },
        {
          "start": "2023-08-29T22:00:00+02:00",
          "end": "2023-08-29T22:00:00+02:00"
        },
        {
          "start": "2023-08-30T12:00:00+02:00",
          "end": "2023-08-30T14:00:00+02:00"
        },
        {
          "start": "2023-09-04T06:00:00+02:00",
          "end": "2023-09-04T07:00:00+02:00"
        }
      ],
      "id": "4"
    }
  ],
  "required_workers": [
    {
      "start": "2023-08-29T09:00:00+02:00",
      "end": "2023-08-29T09:30:00+02:00",
      "count": 2
    },
    {
      "start": "2023-08-29T09:30:00+02:00",
      "end": "2023-08-29T10:00:00+02:00",
      "count": 3
    },
    {
      "start": "2023-08-29T10:00:00+02:00",
      "end": "2023-08-29T10:30:00+02:00",
      "count": 1
    },
    {
      "start": "2023-08-29T10:30:00+02:00",
      "end": "2023-08-29T11:00:00+02:00",
      "count": 2
    },
    {
      "start": "2023-08-29T11:00:00+02:00",
      "end": "2023-08-29T11:30:00+02:00",
      "count": 4
    },
    {
      "start": "2023-08-29T11:30:00+02:00",
      "end": "2023-08-29T12:00:00+02:00",
      "count": 3
    }
  ]
}

Worker

A worker is used in the input schema.

Field name	Required	Data type	Description	Example
`availability`	Yes	`array` of `availability`	The availability times of the worker	See `availability`
`id`	Yes	`string`	ID for the worker.	`{"id": "1"}`

Availability

Availability is used in the worker schema.

Field name	Required	Data type	SI Unit	Description	Example
`start`	Yes	`timestamp`	NA	The start of an availability time window for a worker.	`{"start": "2023-01-01T00:00:00Z"}`
`end`	Yes	`timestamp`	NA	The end of an availability time window for a worker.	`{"end": "2023-01-01T00:00:00Z"}`

Required Worker

A worker is used in the input schema.

Field name	Required	Data type	Description	Example
`start`	Yes	`timestamp`	The start of a required worker time window.	`{"start": "2023-01-01T00:00:00Z"}`
`end`	Yes	`timestamp`	The end of a required worker time window.	`{"end": "2023-01-01T00:00:00Z"}`
`count`	Yes	`int`	The number of required workers for that time window.	`{"count": 1}`

Output

The output schema defines the solution to the shift scheduling problem in JSON format. The output schema contains the following components.

Field name	Always present	Data type	SI Unit	Description	Example
`solutions`	Yes	`array` of `solution`	NA	Solutions to the shift scheduling problem.	`{"solutions": []}`
`statistics`	Yes	`statistics`	NA	Summary statistics of the solution.	`{"statistics": {"total_cost": 123}}`
`version`	Yes	`string`	NA	Version of the Nextmv SDK used to generate the solution.	`{"version": {"sdk": "v1.2.3"}}`
`options`	No	`object`	NA	Arbitrary model and solver options that were used.	`{"options": {"foo": "bar"}}`

JSON

{
  "options": {
    "limits": {
      "day": {
        "max_duration": 36000000000000
      },
      "shift": {
        "max_duration": 28800000000000,
        "min_duration": 7200000000000,
        "recovery_time": 28800000000000
      },
      "week": {
        "max_duration": 144000000000000
      }
    },
    "penalty": {
      "over_supply": 1000,
      "under_supply": 500
    },
    "solve": {
      "control": {
        "bool": [],
        "float": [],
        "int": [],
        "string": []
      },
      "duration": 10000000000,
      "mip": {
        "gap": {
          "absolute": 0.000001,
          "relative": 0.0001
        }
      },
      "verbosity": "off"
    }
  },
  "solutions": [
    {
      "assigned_shifts": [
        {
          "end": "2023-08-29T11:00:00+02:00",
          "start": "2023-08-29T03:00:00+02:00",
          "worker_id": "3"
        }
      ],
      "number_assigned_workers": 1
    }
  ],
  "statistics": {
    "result": {
      "custom": {
        "constraints": 2713,
        "provider": "highs",
        "status": "optimal",
        "variables": 913
      },
      "duration": 0.116243292,
      "value": 5500
    },
    "run": {
      "duration": 0.116243292
    },
    "schema": "v1"
  },
  "version": {
    "sdk": "VERSION"
  }
}

Solution

Field name	Always present	Data type	SI Unit	Description	Example
`assigned_shifts`	Yes	`array` of `assigned_shift`	NA	Solution to the shift scheduling problem.	`{"assigned_shifts": []}`
`number_assigned_workers`	Yes	`int`	NA	The number of assigned distinct workers.	`{"number_assigned_workers": 1}`

Assigned shift

Field name	Always present	Data type	SI Unit	Description	Example
`start`	Yes	`timestamp`	NA	Start time of the worker's shift	`{"start": "2023-01-01T00:00:00Z"}`
`end`	Yes	`timestamp`	NA	End time of the worker's shift	`{"end": "2023-01-01T00:00:00Z"}`
`worker_id`	Yes	`string`	NA	The ID of the worker assigned to this shift.	`{"id": "1"}`

Statistics

Field name	Always present	Data type	SI Unit	Description	Example
`result`	No	`result`	NA	Final result of the solutions.	See `result`
`run`	Yes	`run`	NA	Information about the run.	See `run`
`schema`	Yes	`string`	NA	Schema of the statistics.	`{"schema": "v1"}`

Here you can find additional definitions used in the statistics schema:

result

Field name	Always present	Data type	SI Unit	Description	Example
`duration`	Yes	`float`	`seconds`	Time duration to get to the final result.	`{"duration": 0.123}`
`value`	Yes	`float`	NA	Value of the final result.	`{"value": 0.123}`
`custom`	Yes	`any`	NA	Custom solver metrics.	See `custom`

run
Field name Always present Data type SI Unit Description Example
duration Yes float seconds Time duration of the run. {"duration": 0.123}

Field name	Always present	Data type	SI Unit	Description	Example
`duration`	Yes	`float`	`seconds`	Time duration of the run.	`{"duration": 0.123}`

custom

Field name	Always present	Data type	SI Unit	Description	Example
`constraints`	Yes	`int`	NA	Number of constraints.	`{"constraints": 123}`
`provider`	Yes	`string`	NA	Solver provider.	`{"provider": "highs"}`
`status`	Yes	`string`	NA	Solver status.	`{"status": "optimal"}`
`variables`	Yes	`int`	NA	Number of variables.	`{"variables": 123}`

A reference for the input and output schemas in shift scheduling.