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
| Field | Required | Type | Description |
|---|---|---|---|
| kind | yes | "timeline" | Must be exactly "timeline" |
| title | no | string | Title rendered above the diagram |
| events | yes | array of Event | At least two events required |
Event fields
| Field | Required | Type | Description |
|---|---|---|---|
| date | milestone | string | The milestone's date |
| start | period | string | First date of the period |
| end | period | string | Last date of the period (inclusive) |
| label | yes | string | Text displayed with the milestone marker or period bar |
| emphasis | no | "primary" | "secondary" | Importance — see the shared Emphasis field |
| status | no | "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
dateor a periodstart, 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.
emphasisandstatusare the shared optional fields. Aprimarymilestone has a larger marker and a bold label, aprimaryperiod a bold label and a background-colored outline;secondarytints the marker or bar lighter. Astatusother thannormaldraws 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
Milestones and periods
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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
events[].label | 4 milestones | 10 / 10 | 19 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | timeline |
title | string | no |
events — 2 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
date | date | no | a milestone |
start | date | no | a period; with end |
end | date | no | a period; with start |
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
Rules
- each event has a
date, or bothstartandend, not both kinds endis not beforestart