ADR 0018 supported date range

ADR-0018: Supported date range 0001-01-02 to 9999-12-30

The public API covers fiscal years that lie wholly between 0001-01-02 and 9999-12-30, and any other fiscal year returns OUT_OF_RANGE.

Last reviewed: 31 Oct 2026

Status

Accepted on 31 Oct 2026 by maintainer decision. The range comes from the research proposal ("Edge cases and correctness rules") and finding 6 of the gap analysis; the maintainer accepted it as a separate ADR, which the original ADR list did not have. Built in 0.1.0.

Context

An earlier draft supported years 1 to 9999 to match Python's date. The gap analysis found two problems. The last period's end_exclusive would be 10000-01-01, and in Python date(9999, 12, 31) + timedelta(days=1) raises OverflowError (check C18 in research/verification/). And a week-based year near the start of the range can begin in year 0.

Because periods are half-open (ADR-0007), the day after the last period must be representable in every language.

Decision drivers

• Every value the API returns must be representable as a native date in Rust, Python and JavaScript.
• Dates outside the range must give an error, never a guess.
• Whole-range validation needs a finite range.

Considered options

Option 1: Years 1 to 9999

Pros:

• Matches Python's date range.

Cons:

• The final end_exclusive overflows Python's date (C18), and week-based years can start in year 0.

Option 2: Fiscal years wholly inside 0001-01-02 to 9999-12-30 (chosen)

Pros:

• Leaves one day at each end, so every start and end_exclusive fits in Python's date.

Cons:

• The usable range depends on the calendar: the first and last fiscal years that fit differ by definition.

Option 3: An unbounded range

Pros:

• No edge to document.

Cons:

• Bindings cannot represent the results, and whole-range validation cannot finish.

Decision

Option 2, stated in spec/definition-v1.md ("Supported range"). A date in, or a request for, any other fiscal year returns OUT_OF_RANGE. The core's Date stores an i32 day number (ADR-0003). Validation checks rules such as year-number uniqueness across every fiscal year in the range (ADR-0029).

Consequences

Good:

• No binding can receive a date it cannot represent.
• Whole-range validation is finite: at most about 10,000 fiscal years per definition.

Bad:

• Callers near the edges get OUT_OF_RANGE for fiscal years that partly overlap the range.
• Year numbers after offset that fall outside 1 to 9999 cannot be formatted with {yyyy}, so format returns OUT_OF_RANGE and dimension label columns are null.

Links

• Semantics, Definition-Format, Evidence
• research/verification/README.md (C18)
• Related: ADR-0003, ADR-0007, ADR-0029