# Holiday

A holiday: a recurring named day off, such as Nieuwjaarsdag. A holiday carries no calendar date of its own: it is a template whose actual dates live on the free days generated from it, so the same holiday serves every year.

## Used by
- GET /api/v2/holidays: List holidays (HolidayList)
- POST /api/v2/holidays: Create a holiday (Holiday)
- GET /api/v2/holidays/{holiday}: Read a holiday (Holiday)
- PATCH /api/v2/holidays/{holiday}: Update a holiday (Holiday)

## Holiday fields
- id (integer, required): Unique identifier.
- name (string ≤ 255, required): Name of the holiday, e.g. Nieuwjaarsdag.
- default_month (integer or null, required): Month the holiday normally falls in, 1-12. Null means the holiday moves from year to year (Easter, say), and the organisation fills the date in per year on the free day itself.
- default_day (integer or null, required): Day of the month the holiday normally falls on, 1-31, paired with `default_month`. Null means the day is not fixed.
- recurrence_interval (integer or null, required): How often the holiday repeats, in years: `null` is not recurring, 1 is yearly, and n repeats every n years.
- sort_order (integer, required, server-assigned): Position in the organisation's holiday list, ascending. Set by dragging holidays into order in plnnrly; the API exposes no way to reorder holidays.
- free_days_count (integer ≥ 0, required): Number of free days generated from this holiday.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- links (HolidayLinks, required)
  - self (url, required): The canonical URI of this record.
  - free_days (url, required): Free days generated from this holiday.

## Variants

### HolidayList

What a collection returns, and what `?view=summary` returns on a single record.

10 fields.
Identical to the detail object above.

### HolidaySummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

2 fields.
Omits: default_month, default_day, recurrence_interval, sort_order, free_days_count, created_at, updated_at, links

### HolidayLinks

The `links` object on this resource.

Keys: self, free_days

## Example
```json
{
  "id": 1,
  "name": "Nieuwjaarsdag",
  "default_month": 1,
  "default_day": 1,
  "recurrence_interval": 1,
  "sort_order": 1,
  "free_days_count": 1,
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "free_days": "https://<your-url>/api/v2/work-items/1"
  }
}
```