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


# CalendarData

A working calendar: daily working hours, working weekdays and per-date exceptions. Calendars are sent in the `calendars` array of [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/project-data.md>), and tasks and resources point to one by `calendar_id`. Without any calendars, the project uses the built-in `"global"` calendar: Monday to Friday, 08:00-12:00 and 13:00-17:00.

How tasks and resources pick a calendar, and how to turn calendars off, is covered in [Working time and calendars](<https://docs.dhtmlx.com/planning-engine/wasm/scheduling/working-time-calendars.md>) and [`SchedulingConfig`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/scheduling-config.md>) (`calendar_mode`, `use_calendars`).

## Fields

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/common.md#id>) | yes | - | Calendar id. `"global"` replaces the built-in default calendar. Must be unique within `calendars`. |
| `worktime` | [`object`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/calendar-data.md#worktime-fields>) \| `null` | no | built-in hours and days | Working time of the calendar. Omitted or `null` gives Monday to Friday, 08:00-12:00 and 13:00-17:00. |

Unknown fields are ignored. The record must be a JSON object.

### Worktime fields

The working time of one calendar. Each field is optional; an omitted or `null` field keeps its default.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `hours` | `string[]` | no | `["8:00-12:00", "13:00-17:00"]` | Working hour ranges of a working day, each `"H:MM-H:MM"`. `"24:00"` is the only accepted hour-24 value. A range that ends before it starts crosses midnight. |
| `days` | `(boolean \| number)[]` | no | Monday to Friday | Working weekdays. Exactly 7 entries, index `0` is Sunday. `true` or a non-zero number marks a working day; `false` or `0` a day off. |
| `dates` | `{ "YYYY-MM-DD": boolean \| number \| string[] }` | no | `{}` | Exceptions for single dates. Each key is a date, each value a [date rule](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/calendar-data.md#date-rules>). A date rule overrides `days` for that date. |

`customWeeks` and `custom_weeks` aren't supported. Sending either field fails the call with `validation` ("customWeeks is not supported yet").

:::note
A malformed hour range fails the whole call with a `validation` error that has no `path`. In `apply`, this means no operation from that change set is applied.
:::

### Date rules

The value of one `dates` entry.

| Value | Meaning |
|---|---|
| `true` or a non-zero number | Working day with the calendar's `hours` |
| `false` or `0` | Day off |
| `string[]` | Working day with these hour ranges, in the same `"H:MM-H:MM"` format as `hours` |

## Errors

Errors come back in the response envelope of the call that received the data. See [Error handling](<https://docs.dhtmlx.com/planning-engine/wasm/error-handling.md>) for the error fields.

| Error | When |
|---|---|
| `kind: "parse"` | The record or `worktime` isn't a JSON object, `id` is missing, or a `days` entry isn't a boolean or number. |
| `kind: "validation"`, `path: null` | Malformed hour range, `days` without exactly 7 entries, a `dates` key that isn't `YYYY-MM-DD`, or `customWeeks` / `custom_weeks` present. |
| `kind: "validation"`, `path: "calendars[i]"` | Duplicate calendar id, or a calendar with no working time. |

## Used by

- [`schedule`](<https://docs.dhtmlx.com/planning-engine/wasm/api/schedule.md>): through `data_json` ([`ProjectData`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/project-data.md>))
- [`JsonProject.solve`](<https://docs.dhtmlx.com/planning-engine/wasm/api/project-solve.md>): through `data_json` ([`ProjectData`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/project-data.md>))
- [`JsonProject.analyze`](<https://docs.dhtmlx.com/planning-engine/wasm/api/project-analyze.md>): through `data_json` ([`ProjectData`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/project-data.md>))

Calendars can't be added or edited through [`JsonProject.apply`](<https://docs.dhtmlx.com/planning-engine/wasm/api/project-apply.md>). To change them, send full data to `solve`.

## Example

A calendar with 09:00-18:00 working days, a public holiday and one Saturday with morning hours:

```json
{
  "id": "office",
  "worktime": {
    "hours": ["9:00-13:00", "14:00-18:00"],
    "days": [false, true, true, true, true, true, false],
    "dates": {
      "2026-12-25": false,
      "2026-12-19": ["9:00-13:00"]
    }
  }
}
```

## Related

- [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/project-data.md>) - where calendars are sent
- [`SchedulingConfig`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/scheduling-config.md>) - `calendar_mode` and `use_calendars`
- [`TaskData`](<https://docs.dhtmlx.com/planning-engine/wasm/api/types/task-data.md>) - tasks pick a calendar by `calendar_id`
- [Working time and calendars](<https://docs.dhtmlx.com/planning-engine/wasm/scheduling/working-time-calendars.md>) - how tasks and resources pick a calendar