[Canonical page](<https://docs.dhtmlx.com/planning-engine/js/api/types/calendar-data/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# CalendarData

A working-time calendar: which hours of which days count as working time. Pass calendars in [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/project-data.md>)`.calendars`. Tasks and resources pick one through their `calendar_id`. Input only: no call returns it.

## Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) | required | Calendar id, unique among the calendars. The id `"global"` replaces the default calendar. |
| `worktime` | object | Mon-Fri, `8:00-12:00` and `13:00-17:00` | Working-time rules. `null` reads as omitted. |
| `worktime.hours` | `string[]` | `["8:00-12:00", "13:00-17:00"]` | Working hours of a working day, as `"H:MM-H:MM"` ranges. `24:00` is a valid end. An end at or before the start runs past midnight. |
| `worktime.days` | `(boolean \| number)[]` | `[false, true, true, true, true, true, false]` | Exactly 7 entries, Sunday first. `true` or a non-zero number is a working day with `hours`; `false` or `0` is a day off. |
| `worktime.dates` | `Record<string, boolean \| number \| string[]>` | `{}` | Exceptions per date, keyed `"YYYY-MM-DD"`. `true` or a non-zero number is a working day with `hours`, `false` or `0` is a day off, and an array of ranges gives that day its own hours. An exception overrides `days`. |

A field left out of `worktime` keeps its default, so `{ hours: ["9:00-18:00"] }` is a Monday-to-Friday calendar with those hours.

Without a calendar named `"global"`, the default calendar is Monday to Friday, `8:00-12:00` and `13:00-17:00`. How tasks and resources combine their calendars is set by [`SchedulingConfig`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-config.md>)`.calendar_mode`. With `use_calendars: false`, every calendar is ignored and time is flat 24/7. See [Working-time calendars](<https://docs.dhtmlx.com/planning-engine/js/scheduling/working-time-calendars.md>).

## Validation

Each failure throws an [`InputError`](<https://docs.dhtmlx.com/planning-engine/js/api/types/errors.md>) whose `path` points into `calendars`:

| `path` | When |
|---|---|
| `calendars[i]` | Two calendars share an id |
| `calendars[i]` | The calendar has no working time at all |
| `calendars[i].worktime.hours` | A range lies outside `00:00..24:00` |
| `calendars[i].worktime.dates[YYYY-MM-DD]` | A date's range lies outside `00:00..24:00` |
| under `calendars[i].worktime` | A range isn't `"H:MM-H:MM"`, `days` doesn't have 7 entries, a `dates` key isn't a date, or an entry of `days` is an array |
| under `calendars[i].worktime` | `customWeeks` (or `custom_weeks`) is present; it isn't supported |

A `calendar_id` that names no calendar is reported on the task or resource that holds it.

## Used by

- [`Project#solve`](<https://docs.dhtmlx.com/planning-engine/js/api/project-solve.md>): `data.calendars` defines the working time of the loaded plan
- [`Project#analyze`](<https://docs.dhtmlx.com/planning-engine/js/api/project-analyze.md>): `data.calendars` defines the working time of the analyzed dates
- [`schedule`](<https://docs.dhtmlx.com/planning-engine/js/api/schedule.md>): `data.calendars` defines the working time of the plan

## Example

```js
const calendars = [
  // Replace the default calendar: 9 to 18 with a lunch break, Monday to Friday.
  { id: "global", worktime: { hours: ["9:00-13:00", "14:00-18:00"] } },
  // A night shift, Monday to Saturday, with a holiday and a short day.
  {
    id: "night",
    worktime: {
      hours: ["22:00-6:00"],
      days: [false, true, true, true, true, true, true],
      dates: {
        "2026-12-25": false,
        "2026-12-31": ["22:00-2:00"],
      },
    },
  },
];
```

## Related

- [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/project-data.md>) - the plan that carries `calendars`
- [`SchedulingConfig`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-config.md>) - `calendar_mode` and `use_calendars`
- [`TaskData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-data.md>) - a task's `calendar_id`
- [Working time and calendars](<https://docs.dhtmlx.com/planning-engine/js/scheduling/working-time-calendars.md>) - defining calendars and how they combine