Dates and times

All three are held once for every locale. Times are stored with the zone they belong to, so a 19:00 start stays 19:00 on both sides of a clock change.

dateCopy Anchor Link

A calendar day with no time and no zone: an opening date, a deadline, a date of birth.

fields:
  - { name: openedOn, type: date, min: "1800-01-01" }
  - { name: closesOn, type: date, index: true }

Stored value: a string, "2026-04-01". With index: true it is projected as that day at midnight UTC, so lists filter and sort by it.

Template value: a date value. Format it with |date, which writes the day in the request locale’s words and order:

<p>Open since {{ entry.openedOn|date:"long" }}</p>
<time datetime="{{ entry.openedOn.date }}">{{ entry.openedOn|date }}</time>

A date field reads an old datetime value lossily (its local day) and an ISO date in a text value exactly.

datetimeCopy Anchor Link

A moment in time in the zone it happens in: a publication time, a start time, a deadline at noon in Paris.

fields:
  - { name: doorsOpen, type: datetime, zone: Europe/London }
  - { name: launchAt, type: datetime, min: "2026-01-01T00:00:00Z", seconds: true }
  - { name: festivalDay, type: datetime, all_day: true }

Stored value:

{ "local": "2026-03-29T10:00", "zone": "Europe/Paris", "utc": "2026-03-29T08:00:00Z", "allDay": false }

The wall clock (local) and the zone are what the editor chose; the UTC instant is recomputed from them on every save. In a seed file or an import you may give local and zone alone, or a bare RFC 3339 string, which is read as UTC. With index: true the instant is projected, so lists sort by it.

Template value:

<time datetime="{{ entry.doorsOpen|iso }}">{{ entry.doorsOpen|datetime:"long short" }}</time>
{% if entry.festivalDay.isAllDay %}{{ entry.festivalDay|date:"full" }}{% endif %}

|date, |datetime, |time, |relative and |iso all accept the value directly (Filters). The article type’s core publishedAt is a datetime.

recurrenceCopy Anchor Link

An event’s schedule: a first start and duration in a zone, an optional repeat rule (RFC 5545 RRULE), extra dates, removed dates, and changes to single instances. The core event type’s occurrences field is a recurrence, and a custom type may declare one too.

# config/schema/event.yaml
extends: event
fields:
  - { name: occurrences, label: { en-GB: Dates and times } }   # restate the core field to relabel it

# a custom type
fields:
  - { name: sessions, type: recurrence, zone: Europe/London, all_day: false }

The editor offers once, daily, weekly on chosen days, monthly on a date or an ordinal weekday, yearly, an end by date or count, and a custom rule for anything else, and shows the next instances as the rule is edited.

Stored value:

{
  "start": "2026-03-13T19:00",
  "duration": "PT2H",
  "zone": "Europe/London",
  "allDay": false,
  "rrule": "FREQ=WEEKLY;BYDAY=FR",
  "rdates": ["2026-07-04T19:00"],
  "exdates": ["2026-04-03"],
  "overrides": {
    "5": { "status": "cancelled", "note": "Bank holiday" },
    "6": { "start": "2026-04-25T20:00" }
  }
}

Validation reports each problem at its part: zone (Choose a time zone), start (Enter the first date and time), duration, rrule (The repeat rule is not valid: …), rdates[n], exdates[n] and overrides.<n>.

Occurrences. On save the engine expands the schedule into individual occurrences in local time, then converts each to UTC, for a rolling window around today: 90 days back and 540 days ahead by default (events.occurrence_window in engine.yaml), rolled forward daily. A cancelled instance keeps its row and is marked cancelled; a removed date has none.

Template value. A template never sees the rule’s expansion logic, only the materialised occurrences of the published document:

Each occurrence has startsAt, endsAt (UTC), local, localEnd (wall clock), zone, date (YYYY-MM-DD), isAllDay, isCancelled, isMoved, status, note and ord (its number in the sequence).

<ul>
  {% for o in entry.occurrences.next(5) %}
  <li><time datetime="{{ o.startsAt|iso }}">{{ o.local|datetime:"full short" }}</time>{% if o.note %} ({{ o.note }}){% endif %}</li>
  {% endfor %}
</ul>

Occurrences are read for a top-level recurrence field, and they are the document’s: give a type one recurrence field. How event pages and lists read occurrences is covered in Templates.