How we know we're right

Datewise sells correctness, so "trust us" isn't an acceptable answer. This page describes where the data comes from, how it is checked, what is tested, and — just as important — what we don't cover. Every claim here is checkable: the dataset is downloadable, the hashes recompute, and the live API echoes its versions on every response.

The pipeline, in one paragraph

Holiday data is seeded from the python-holidays library (the vacanza project, MIT licensed — the license covers the data), normalized into a single frozen JSON dataset, content-hashed, and vendored into the API at build time. In CI the dataset is cross-checked against two independent oracles — Nager.Date and OpenHolidaysAPI — and a disagreement blocks the deploy until a human adjudicates it against the jurisdiction's source of record. The API never calls a holiday library or upstream service at request time: it serves only the frozen artifact, which is why answers are deterministic, cacheable, and auditable.

Three imperfect sources → one accountable dataset

1. Seed: python-holidays (vacanza)

A maintained, widely used, MIT-licensed library with per-jurisdiction rules, observed-day logic, and subdivision coverage. It is the seed of record — especially at the subdivision level, where cross-oracle coverage is sparse.

2. Cross-check: independent oracles in CI

Every pipeline run compares the dataset's national-level holidays against Nager.Date and OpenHolidaysAPI. Agreement is required to ship: a real disagreement fails the build (a transient oracle outage is tolerated but logged — third-party downtime can't wedge our pipeline, and it also can't sneak a change through). Subdivision-level data is not cross-checked this way, because oracle coverage there is sparse and divergent — which is exactly why the seed library is the subdivision source of record and why subdivision claims get extra test scrutiny instead.

3. Adjudication: the government source of record

When sources disagree, the tiebreaker is never a vote — it's the jurisdiction's own authority. For the US that is OPM's federal holiday schedule (5 U.S.C. §6103) and state statute for state holidays; for the UK, gov.uk; for Germany, the per-Land holiday statutes.

What "deterministic" means here, concretely

• Every answer is pinned to a version pair. Responses carry X-Dataset-Version and X-Tzdata-Version headers and a meta block. Same inputs + same version pair = same answer, forever.
• A served answer is never silently changed. Corrections ship as a new dataset version with a changelog; old versions are retained forever. If you pin ?dataset=2026.1, your answers are frozen.
• The dataset is content-hashed. The hash is over the canonical JSON body (keys sorted, compact separators, hash field excluded) and includes the seed library version — provenance is part of the fingerprint. You can recompute it yourself from the download below.
• The timezone database is pinned too. Working-hours math depends on tzdata/ICU. The build fails if the runtime's tzdata drifts from the pinned manifest, and the live /health endpoint re-verifies behavioural probes on the serving runtime (tzdata_ok). A tzdata bump is a reviewed change, never a silent one.

Verify it yourself

python3 - <<'EOF'
import json, hashlib, urllib.request
d = json.load(urllib.request.urlopen("https://datewise.dev/datasets/2026.1.json"))
declared = d.pop("content_hash")
canonical = json.dumps(d, sort_keys=True, separators=(",", ":"))
print("declared  ", declared)
print("recomputed", "sha256:" + hashlib.sha256(canonical.encode()).hexdigest())
EOF

How it's tested

• External known-answer vectors. Golden tests assert against independent authorities, not our own output: US OPM federal-holiday day-off tables (including in-lieu-of shifts like July 4, 2026 → observed Friday July 3), and Excel NETWORKDAYS parity for business-day counting semantics.
• DST transition probes. Working-hours arithmetic is tested across spring-forward gaps, fall-back doubled hours, and 30-minute-DST zones (Australia/Lord_Howe) — on zoned wall-clock time, never by adding seconds to a UTC instant.
• Property-based tests. Invariants checked over generated inputs (via fast-check), e.g. business_days_between(d, add_business_days(d, n)) === n, and "a business day is never a weekend or holiday".
• Contract tests. The served OpenAPI spec is asserted in CI to match the implementation exactly — documented paths, error codes, the lot.
• Tests gate deploys. The suite (plus the oracle cross-check) runs in CI on every push; a red suite or a data disagreement blocks the deploy.

What we don't cover — and won't invent

• Coverage bottoms out at ISO 3166-2 subdivisions (states/Länder/countries of the UK). No city or municipal holidays: where a jurisdiction's holidays are genuinely municipal, the answer is "not covered", never an invented value.
• The current dataset covers 2015–2035; nothing before 1970, ever. IANA tzdata is only authoritative from 1970 (earlier offsets are approximations we won't serve as answers), and this preview dataset starts at 2015. Any date outside the covered range — including a pre-2015 date like 1990 — gets an explicit 400 date_out_of_range.
• No dates beyond the dataset ceiling (currently 2035). Far-future holidays are rule-based projections; beyond ~10 years, legislative change makes them speculative. The window rolls forward with each dataset version.
• Preview scope is deliberately narrow. The US is covered in depth — federal plus all 57 ISO 3166-2 subdivisions, each stored as a complete self-contained set (California drops Columbus Day and adds Cesar Chavez Day; that's in the data, not patched in code). GB and DE are national-level only for now. Requesting an unsupported subdivision is a 400, never a silent fallback to national.

Open-source acknowledgements

Datewise is built on open-source software, and the holiday dataset it serves is derived from open-source data. The MIT license under which these are distributed requires that their copyright and permission notices travel with any copy or substantial portion — so we reproduce them here, and in the dataset manifest that ships with the downloadable artifact.

Copyright (c) Vacanza Team and individual contributors (see CONTRIBUTORS file)
Copyright (c) dr-prodigy <dr.prodigy.github@gmail.com>, 2017-2023
Copyright (c) ryanss <ryanssdev@icloud.com>, 2014-2017

Copyright 2019 JS Foundation and other contributors

Copyright (c) 2021 - present, Yusuke Wada and Hono contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

The cross-check oracles — Nager.Date and OpenHolidaysAPI — are used only in CI to validate the dataset, not redistributed, but we're glad to name them too.

Current versions

Live values (recomputed on the serving runtime, not hardcoded here): /health. At the time this page was last updated: dataset 2026.1 covering 2015–2035, content hash sha256:c48e7c61…ba08536e.

Found a date we got wrong? That's exactly the kind of report we want: get in touch and we'll trace it against the source of record — and if we're wrong, the fix ships as a new, changelogged dataset version.