Timeline

A timeline diagram. Events are placed along a horizontal axis at positions proportional to their dates. An event is either a milestone (a single date) or a period (a start and end date). Used for project histories, product roadmaps, and chronological narratives.

Fields

FieldRequiredTypeDescription
kindyes"timeline"Must be exactly "timeline"
titlenostringTitle rendered above the diagram
eventsyesarray of EventAt least two events required

Event fields

FieldRequiredTypeDescription
datemilestonestringThe milestone's date
startperiodstringFirst date of the period
endperiodstringLast date of the period (inclusive)
labelyesstringText displayed with the milestone marker or period bar
emphasisno"primary" | "secondary"Importance — see the shared Emphasis field
statusno"success" | "normal" | "warning" | "critical"Condition — see the shared Status field

Each event declares either date (a milestone) or both start and end (a period). Any other combination is a validation error.

Dates

All date fields accept YYYY, YYYY-MM, or YYYY-MM-DD, and must name a real calendar date (2024-02-30 is rejected). A partial date names a whole year or month:

  • As a milestone date or a period start, it is placed at the first day of that year/month.
  • As a period end, it is inclusive — the period runs through the last day of that year/month (or through that day, for a full date). start = "2024-02", end = "2024-03" covers February and March.

end must not fall before start. A period may be a single year, month, or day (start = end).

Rendering rules

  • Events are sorted by date (a period by its start) and placed along a horizontal axis.
  • The horizontal position of each event is proportional to its date within the overall date range, which spans from the earliest date to the latest milestone or period end.
  • Milestones are markers on the axis. Their labels alternate above and below the axis to reduce overlap, and the date string is displayed below each marker.
  • Periods are bars below the axis, spanning their dates, with the label inside the bar (or beside it when the bar is too short) and the date range underneath. Overlapping periods stack into separate rows; periods that do not overlap share a row.
  • emphasis and status are the shared optional fields. A primary milestone has a larger marker and a bold label, a primary period a bold label and a background-colored outline; secondary tints the marker or bar lighter. A status other than normal draws a small marker, dual-encoded by color and shape: beside a milestone's label, and in the right end of a period bar (just right of a bar too narrow to hold its label). The two fields are independent — an event may carry both.
  • At least two events are required to establish a time range.
  • This is a qualitative roadmap, not a scheduler: there are no dependencies, progress, or resource fields. Use a project-management tool for precise Gantt charts.

Example

Product Launch History Timeline: 2024-01-15 Alpha; 2024-04-01 Beta; 2024-07-20 Launch; 2024-12-01 v2.0. Product Launch History Alpha 2024-01-15 Beta 2024-04-01 Launch 2024-07-20 v2.0 2024-12-01

Milestones and periods

Product Roadmap 2024 Timeline: 2024-01-15 Kickoff; 2024-02 to 2024-04 Private Beta; 2024-03 to 2024-09 Enterprise Pilot; 2024-05 to 2024-06 Public Beta; 2024-07-01 GA Launch. Product Roadmap 2024 Kickoff 2024-01-15 GA Launch 2024-07-01 Private Beta 2024-02 – 2024-04 Enterprise Pilot 2024-03 – 2024-09 Public Beta 2024-05 – 2024-06

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
events[].label4 milestones10 / 1019 / 19

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyestimeline
titlestringno

events — 2 or more elements

FieldTypeRequiredValues / meaning
datedatenoa milestone
startdatenoa period; with end
enddatenoa period; with start
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

Rules

  • each event has a date, or both start and end, not both kinds
  • end is not before start