Calendars, Holidays and Events

The naive model of a calendar — a currency or country code mapped to a set of excluded dates — is sufficient for the narrow purpose of computing a business day, and it is essentially what QuantLib's Calendar class provides: a name, an algorithmic rule for most holidays (fixed dates, nth-weekday-of-month rules, and pre-tabulated lunar-calendar holidays for markets such as China, Japan or the Gulf states where no closed-form rule exists), and an escape hatch — addHoliday=/=removeHoliday — for holidays that must be entered ad hoc, without recompiling the library, because they were only announced recently or apply to a single year. QuantLib further composes several such calendars into a JointCalendar, under either join-holidays (union: a day is a holiday if any constituent calendar says so) or join-business-days (intersection: a day is a holiday only if every constituent calendar agrees) semantics — the same union rule a comma-joined list of calendar names implicitly expresses wherever that free-text convention is used.

What distinguishes a reference-data model of calendars from QuantLib's purely computational one is that a calendar administration screen needs to do considerably more than enumerate excluded dates: holidays must be addable, removable and disable-able (as distinct from deleted, preserving the historical record); they can be historic, can span multiple days, and can fall on a weekend without being erroneous; they can be sourced from an external feed and require authorisation before taking effect, unless the source is marked trusted, in which case they activate automatically; and the calendar should also anchor events, while the actual effect of an event is modelled elsewhere. That last point is the entire content of the Diary/Effects split, stated in one line: the calendar is the anchor for both holidays and events, but it is not where either kind of entry's downstream consequences live.

• The diary itself — a validated enumeration of calendar codes and the time points recorded against them — should stay semantics-free, carrying only codes and time points, and should not accrete typed fields for every possible downstream consumer; see The Diary/Effects Model for why.
• A currency, or any other entity, can need more than one calendar at once (a national public-holiday calendar and a financial-centre calendar, say), and a recurring holiday needs to be entered once via a template rather than instance-by-instance every year — both covered in Holiday Calendar Administration.
• An event — a time point with one or more associated currencies, and, deliberately, no modelled effect — is a first-class kind of diary entry distinct from a holiday, covered in Calendar Events, which also surveys where genuine event data (central bank policy-meeting dates) can be sourced. The event store has landed in code as a single calendar_event table with a diary_entry_types vocabulary (decided 2026-08-09, FOMC analysis) — one table for all event kinds, never a table per calendar or per type.

A calendar feeds two distinct downstream layers. Fixing and coupon schedule generation — the machinery by which an IRS or similar structured product turns a compact parameter set (Pay Period, Fix Period, Yield Basis, Number of Coupons) into a concrete set of fixing and coupon dates, in the spirit of QuantLib's Schedule and MakeSchedule — consumes a calendar together with a business-day convention, of the kind catalogued in Date Rolling and Business-Day Calendars, to produce per-deal pricing-time dates. The broader lifecycle-event taxonomy of a trade — Confirmable Events, System Events, the deal state machine, automatic deal generation off a fixing or expiry — treats the calendar as one of several event sources: a life-cycle event can be triggered by the calendar (a fixing, an expiry), exactly as Calendar Events describes.