In part 1 I explained why I started hldays: I kept forgetting my municipal holiday, and found out that every Portuguese municipality has its own.

This post is about the first real problem: how do you model holidays so the same API works for Lisbon, Bavaria and Texas?

The naive version

My first mental model was a table:

date name country

2026-12-25 Christmas PT

That breaks almost immediately:

Holidays aren't dates, they're rules. Christmas is "25 December". Good Friday is "two days before Easter". Thanksgiving is "fourth Thursday of November". You can't store 2016 to 2099 by hand.

Holidays aren't national. Bavaria has Epiphany, Berlin doesn't. Madeira has Madeira Day. Braga has São João on 24 June.

Places have different shapes. Portugal has districts, two autonomous regions and 308 municipalities. Germany has states. The US has states and territories.

So the model became two things: a tree of jurisdictions, and a set of rules attached to them.

1.…