JSON Reference

A jsonantt file is a single JSON object with the following top-level keys.

Top-level fields

Field	Type	Default	Description
tasks	array	required	Ordered list of task objects.
title	string	""	Chart title. Omit to render without a title and without wasting vertical whitespace.
dateformat	string	"%Y-%m-%d"	strftime format string used to parse all dates in the file.
start	string	auto	Force the x-axis start date (overrides the earliest task date).
end	string	auto	Force the x-axis end date (overrides the latest task date).
style	object	see Style Guide	Visual style overrides. See Style Guide for all fields.

Task object

Each entry in tasks (and each entry in a task’s children array) is a task object.

Field	Type	Default	Description
name	string	required	Display label for the task.
description	string	""	Optional long description (unused in chart output, available in table columns).
id	string	—	Unique identifier used in not_before references.
start	string	—	Start date in dateformat. Required unless derived from children or not_before.
end	string	—	End date in dateformat. Omit when using duration.
duration	string	—	Duration relative to start or the end of the not_before task. Format: <N><unit>. See duration units table below.
not_before	string	—	id of another task. This task’s start is automatically set to that task’s effective end date. Must be paired with duration.
color	string	palette	Hex color for this task’s bar or milestone marker. Children without an explicit color inherit this value (and can be auto-lightened via subtask_lightening_pct).
milestone	boolean	false	When true the task is rendered as a diamond marker, not a bar.
date	string	—	The milestone date. Used only when milestone: true.

Milestone field summary

Field	Type	Default	Description
milestone	boolean	false	Render as a marker instead of a bar
date	string	—	Point-in-time date for the milestone
color	string	style default	Marker fill color (e.g. "#FFD700")
marker	string	"D"	Matplotlib marker: "D" diamond, "*" star, "^" triangle
marker_size	number	14.0	Override marker size in points

Example: milestones with different markers

{
  "title": "Milestone Markers",
  "dateformat": "%Y-%m-%d",
  "style": { "major_tick": "quarter", "minor_tick": "month" },
  "tasks": [{
    "name": "Project Alpha",
    "children": [
      { "name": "Discovery",   "start": "2025-01-06", "end": "2025-02-07" },
      { "name": "Design done", "milestone": true, "date": "2025-04-01",
        "color": "#FFD700" },
      { "name": "Development", "start": "2025-04-01", "end": "2025-07-18" },
      { "name": "Beta launch", "milestone": true, "date": "2025-07-21",
        "color": "#FF6B6B", "marker": "*", "marker_size": 16 },
      { "name": "GA release",  "milestone": true, "date": "2025-09-15",
        "color": "#70AD47" }
    ]
  }]
}

Other task fields

Field	Type	Default	Description
bold	boolean	false	Force bold label text on this task (independent of bold_tasks).
marker	string	"D"	Matplotlib marker symbol for milestones. "D" = diamond, "*" = star, "^" = triangle, etc.
marker_size	number	style default	Override the milestone marker size in points for this task only.
children	array	[]	Nested sub-tasks. A task with children derives its start/end from the earliest/latest child dates. The bar is rendered as a summary bar (thinner, with a different appearance).
(any)	any	—	Any additional field is stored on the task and is accessible as a table column via style.table_columns. Example: "cost": 50000, "owner": "Alice".

Duration units

Suffix	Unit	Behaviour
d	Days	Exact calendar days. "14d" = 14 days.
w	Weeks	7 calendar days each. "2w" = 14 days.
m	Months	Calendar months. "3m" from Jan 6 ends Apr 6.
y	Years	Calendar years. "1y" from Jan 1 2024 ends Jan 1 2025.

Examples: "90d", "3m", "2w", "1y", "18m".

Duration and chaining example

{
  "title": "Duration & not_before Scheduling",
  "dateformat": "%Y-%m-%d",
  "tasks": [
    { "id": "design",   "name": "Design",
      "start": "2025-01-06", "duration": "2m", "color": "#4472C4" },
    { "id": "backend",  "name": "Backend",
      "not_before": "design", "duration": "3m", "color": "#70AD47" },
    { "id": "frontend", "name": "Frontend",
      "not_before": "design", "duration": "2m", "color": "#ED7D31" },
    { "id": "qa",       "name": "QA & Testing",
      "not_before": "backend", "duration": "6w", "color": "#FF5757" }
  ]
}

Date resolution order

jsonantt resolves each task’s start and end using the first applicable rule:

1. Explicit start + end — used as-is.

2. Duration start + duration — end is computed.

3. Chain not_before + duration — start is set to the effective end of the referenced task; end is then computed.

4. Parent — a task with no dates and no not_before/duration derives its range from its children.

Minimal example

{
  "dateformat": "%Y-%m-%d",
  "tasks": [
    {
      "name": "Project",
      "children": [
        { "name": "Kick-off",  "start": "2025-01-06", "end": "2025-01-17" },
        { "name": "Delivery",  "milestone": true, "date": "2025-06-30", "color": "#FFD700" }
      ]
    }
  ]
}

Full skeleton

{
  "title": "My Project",
  "dateformat": "%Y-%m-%d",
  "start": "2025-01-01",
  "end":   "2025-12-31",
  "style": {
    "major_tick": "year",
    "minor_tick": "quarter"
  },
  "tasks": [
    {
      "id": "phase1",
      "name": "Phase 1",
      "color": "#4472C4",
      "children": [
        {
          "id": "task-a",
          "name": "Task A",
          "start": "2025-01-06",
          "duration": "6w"
        },
        {
          "id": "task-b",
          "name": "Task B",
          "not_before": "task-a",
          "duration": "2m"
        },
        {
          "name": "Phase 1 done",
          "milestone": true,
          "date": "2025-04-01",
          "color": "#FFD700"
        }
      ]
    }

  ]
}