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


# TaskData

One task, summary or milestone as a plain object. Put tasks in [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/project-data.md>)`.tasks` to load a plan, or in [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-changes.md>)`.tasks.add` to add them to a live project. No call returns `TaskData`: scheduled dates come back as update entries in [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/js/api/types/schedule-result.md>).

## Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) | required | Task id, unique among the project's tasks. |
| `parent` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) `\| null` | no parent | Id of the parent task. `""` or a value equal to [`SchedulingConfig`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-config.md>)`.root_id` also means a top-level task. |
| `type` | `"task" \| "summary" \| "project" \| "milestone"` | `"task"` | Plain task, summary or milestone. `"project"` is an alias of `"summary"`. Decides which date fields are needed, see [Dates by task type](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-data.md#dates-by-task-type>). |
| `start_date` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) `\| null` | none | Start of the task. |
| `end_date` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) `\| null` | none | End of the task. Must not be before `start_date`. |
| `duration` | `number \| null` | none | Working time in `duration_unit`. Finite and `>= 0`. |
| `duration_unit` | [`TimeUnit`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#timeunit>) `\| null` | `config.duration_unit` | Unit of `duration`, `leveling_delay` and `pauses`. |
| `constraint_type` | [`ConstraintType`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#constrainttype>) `\| null` | none | Date constraint: `"asap"`, `"alap"`, `"snet"`, `"snlt"`, `"fnet"`, `"fnlt"`, `"mso"` or `"mfo"`. Takes effect only when `config.apply_constraints` is `true`. |
| `constraint_date` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) `\| null` | none | Date of the constraint. Required for every `constraint_type` except `"asap"` and `"alap"`. |
| `auto_scheduling` | `boolean \| null` | `true` | `false` fixes the task: the scheduler never moves it. |
| `unscheduled` | `boolean \| null` | `false` | `true` leaves the task and all its descendants out of scheduling and out of results. Such tasks need no dates. |
| `progress` | `number \| null` | `0` | Completed share, from `0` to `1`. With `config.use_progress`, `1` marks the task completed and fixed. |
| `priority` | `number \| null` | `500` | Leveling priority, an integer from `0` to `1000`. Read only by [`Project#level`](<https://docs.dhtmlx.com/planning-engine/js/api/project-level.md>). |
| `leveling_delay` | `number \| null` | `0` | Elapsed time added before the task's driven start, in `duration_unit` (a day is 24 hours). Finite and `>= 0`. Written by [`Project#level`](<https://docs.dhtmlx.com/planning-engine/js/api/project-level.md>). |
| `pauses` | [`Pause`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#pause>)`[] \| null` | `[]` | Splits in the task's work, sorted by `at` and non-overlapping. Written by [`Project#level`](<https://docs.dhtmlx.com/planning-engine/js/api/project-level.md>). Ignored on summaries, milestones and unscheduled tasks. |
| `calendar_id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) `\| null` | none | Id of the task's working calendar: an entry of `ProjectData.calendars`, or `"global"`. Without it the task uses the `"global"` calendar, or its nearest ancestor's calendar when `config.calendar_mode` is `"task-inherited"`. |

`null` on any optional field reads the same as leaving the field out. Unknown fields are ignored, so task objects from a Gantt UI can be passed as they are. Date fields take a string or a local `Date`; see [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>).

## Dates by task type

`start_date`, `end_date` and `duration` are read differently for each `type`. Unscheduled tasks skip these rules.

| `type` | Accepted input | Result |
|---|---|---|
| `"task"` | `start_date` + `duration` | End computed forward on the task's calendar, around any `pauses`. |
| `"task"` | `end_date` + `duration` | Start computed backward from the end. |
| `"task"` | `start_date` + `end_date` | `duration` is the working time between the dates. |
| `"task"` | all three | Accepted only when `start_date` + `duration` lands on `end_date`. |
| `"summary"` | `start_date` + `end_date` | The given span. `duration` is ignored. |
| `"summary"` | neither date | Span taken from the dated children. |
| `"milestone"` | `start_date` or `end_date` | A zero-length task at that date. `duration` is ignored. |

A summary with only one of the two dates is an error, and so is a plain task with fewer than two of the three fields.

## Errors

With the default `validation: "strict"` (see [`Project`](<https://docs.dhtmlx.com/planning-engine/js/api/project.md>)), an invalid task makes [`Project#solve`](<https://docs.dhtmlx.com/planning-engine/js/api/project-solve.md>), [`Project#analyze`](<https://docs.dhtmlx.com/planning-engine/js/api/project-analyze.md>) and [`schedule`](<https://docs.dhtmlx.com/planning-engine/js/api/schedule.md>) throw an [`InputError`](<https://docs.dhtmlx.com/planning-engine/js/api/types/errors.md>) with `kind: "validation"` at a path under `tasks[i]`:

| `path` | When it occurs |
|---|---|
| `tasks[i].progress` | `progress` isn't finite or is outside `0..1` |
| `tasks[i].leveling_delay` | `leveling_delay` isn't finite or is negative |
| `tasks[i].duration` | `duration` isn't finite or is negative; or all three date fields are set and disagree |
| `tasks[i].constraint_date` | a dated `constraint_type` has no `constraint_date` |
| `tasks[i].pauses[j]` | pause `j` has a negative or non-finite `at`, a non-finite or non-positive `length`, or is out of order or overlaps the previous one |
| `tasks[i].calendar_id` | `calendar_id` names no calendar in `ProjectData.calendars` and isn't `"global"` |
| `tasks[i].start_date` | a plain task has fewer than two of `start_date`, `end_date`, `duration`; a summary has only one date; a milestone has no date |
| `tasks[i].end_date` | `end_date` is before `start_date` |
| `tasks[i]` | a summary has no dates and no dated children |

A `priority` that isn't a whole number from `0` to `1000` throws an `InputError` with `kind: "validation"` and `path: null`. Rules across tasks (unique ids, known parent, no hierarchy cycle) are on [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/project-data.md>). `validation: "repair"` fixes several of these cases instead of throwing.

## Used by

- [`Project#solve`](<https://docs.dhtmlx.com/planning-engine/js/api/project-solve.md>), [`Project#analyze`](<https://docs.dhtmlx.com/planning-engine/js/api/project-analyze.md>), [`schedule`](<https://docs.dhtmlx.com/planning-engine/js/api/schedule.md>): through `ProjectData.tasks`
- [`Project#apply`](<https://docs.dhtmlx.com/planning-engine/js/api/project-apply.md>), [`Project#preview`](<https://docs.dhtmlx.com/planning-engine/js/api/project-preview.md>): through `SchedulingChanges.tasks.add`

## Example

A summary with two dated children, a constrained task and a milestone:

```js
const tasks = [
  { id: "phase", type: "summary" },
  { id: "design", parent: "phase", start_date: "2026-04-06 08:00", duration: 2 },
  {
    id: "build",
    parent: "phase",
    start_date: "2026-04-06 08:00",
    duration: 3,
    constraint_type: "snet",
    constraint_date: "2026-04-10 08:00",
  },
  { id: "release", type: "milestone", start_date: "2026-04-10 08:00" },
];
```

## Related

- [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/project-data.md>) - the plan that carries `tasks`
- [`TaskUpdate`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-update.md>) - editing an existing task
- [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/js/api/types/schedule-result.md>) - where scheduled dates come back
- [Project data](<https://docs.dhtmlx.com/planning-engine/js/scheduling/project-data.md#tasks>) - task types, dates and durations
- [Links, constraints and summaries](<https://docs.dhtmlx.com/planning-engine/js/scheduling/links-constraints-summaries.md>) - how links, constraints and summaries move tasks