Holiday Semantics

How JDay represents holidays — observed dates, plural arrays, and the holiday object model.

JDay uses one consistent holiday object across all endpoints.

Holiday Object

{
  "date": "2026-04-03",
  "official_date": null,
  "name": "Good Friday",
  "local_name": null,
  "type": "public",
  "date_accuracy": "exact"
}

Field	Type	Description
`date`	`string`	The effective non-working date used by the engine.
`official_date`	`string \| null`	The official/legal date when it differs from `date`, otherwise `null`.
`name`	`string`	English display name.
`local_name`	`string \| null`	Localized/native name when available, otherwise `null`.
`type`	`string`	`"public"` or `"regional"`.
`date_accuracy`	`string`	`"exact"` or `"estimated"`.

When a holiday falls on a weekend but is observed on a weekday:

date contains the weekday observed closure date (the date the engine uses)
official_date contains the weekend official date
The engine matches against date, not official_date

Holiday-bearing responses always use arrays, not singular fields. This is because:

Multiple holidays can share the same effective date in a jurisdiction
Arrays are always sorted by date ascending, then name ascending as a deterministic tie-breaker

When no holidays apply, the array is empty ([]), never omitted.

"exact" — Fixed or rule-based dates already determined.
"estimated" — Holidays whose final date may shift due to moon sighting or official late confirmation. When an official date is confirmed, JDay updates the data and redeploys.

When a response includes a single reason field (e.g., is-business-day), precedence is:

The holidays array may still contain holiday records even if reason is weekend — the reason is the primary classification, not exclusive.