Analysis

Analysis

Real fiscal calendars combine three independent choices (how the year is bounded, subdivided and named), and no existing open library models them as data shared across Rust, Python and JavaScript.

Last reviewed: 1 Nov 2026

This page summarises the research proposal and the gap analysis, with the corrections that re-checking on 31 Oct 2026 required. Every source and check is on the Evidence page; requirements are on the PDR page. Terms follow the Glossary. Example calendars on this page are descriptions of what sources say, not definitions checked as conformance vectors, unless a vector is named.

Calendar families

Textbooks describe four families. The proposal lists them as follows; the "typical users" column is the proposal's description and is not separately sourced.

Family	How the year is built	Typical users (proposal)	Where code breaks
Calendar-month year (in the Glossary, a fixed-date year)	Starts on a fixed month and day and runs 12 calendar months	Governments, most companies	Start days 29–31; naming of the year
52/53-week year (a week-based year)	Ends on the same weekday each year: the last such weekday of a month, or the one nearest the month's end	Retailers, manufacturers, hardware makers	The 53rd week; year ends drifting across months
4-4-5 family	A 52/53-week year whose 13-week quarters split 4-4-5, 4-5-4 or 5-4-4 weeks	Retail, restaurants, manufacturing	Where the extra week goes
13-period year	Thirteen 4-week periods plus an extra week every 5–6 years	Hospitality, grocery, wholesale	Period 13; no natural quarters

The two 52/53-week rules come from the US tax rules for a 52-53-week tax year: the chosen weekday "last occurs in a calendar month" or falls "nearest to the last day of the calendar month" (IRS Publication 538, quoted in full on the Evidence page). fiscalclock writes these as rule: "last" and rule: "nearest", and adds rule: "first" and edge: "start".

Every one of the 168 "last" and "nearest" rules (7 weekdays, 12 months, 2 rules) gives exactly 71 years of 53 weeks in each of two 400-year windows, because 400 Gregorian years hold exactly 20,871 weeks (checks C01 and C02 in research/verification/). The ISO 8601 week-numbering year is the week-based year that starts on the Monday nearest 1 January, for every year from 1600 to 2399 (C15).

Shapes the families miss

Each shape below breaks an assumption that a family-based design would make. Text in quotation marks is verbatim; corrections from re-checking are stated in the row.

Shape	Example and source	Assumption it breaks	fiscalclock
Fixed-date year with week-based quarters	Vishay's 10-Q describes "13-week periods beginning on a Sunday and ending on a Saturday, except for the first fiscal quarter, which always begins on January 1, and the fourth fiscal quarter, which always ends on December 31" (Vishay 10-Q). The filing does not name the Q1 anchor. Reported Q1 ends of 1 Apr 2023 and 30 Mar 2024 match "Saturday nearest 31 March", but that anchor stays illustrative until a cited vector exists.	Week-based periods need a week-based year	stub, 0.2, ADR-0024 (Accepted, 1 Nov 2026; resolves D1 and D4)
Rule-anchored periods	The broadcast calendar: "The standard broadcast week starts on Monday and ends on Sunday. The standard broadcast month ends on the last Sunday of the calendar month." (TVB). Its months run 4-4-5 in every quarter of 2024 (C11), and 2029's quarters are 12, 13, 14 and 13 weeks (C13). Correction: the proposal's "5-4-4 in 2021" holds for Q1 and Q4 only; Q2 and Q3 run 4-5-4 (C12a).	Periods follow a fixed week pattern	anchored subdivision, 0.2
Uneven quarters	Costco's 10-K: "thirteen, four-week periods", with four periods in Q4 (Costco 10-K). Kroger's 10-K: "thirteen 28-day periods", with a three-period Q4 (Kroger 10-K).	Quarters are 13 weeks	quarters lists periods per quarter; built in 0.1.0
Different rules for quarter and year ends	Care.com's fiscal 2019 Q2 10-Q gives the year end as "the Saturday in December closest and prior to December 31" and quarter ends "on the Saturday that falls closest to the last day of the third month" (Care.com 10-Q). Read as "on or before 31 December", the two rules give different Q4 ends in 2020, 2021 and 2025–2027 within 2019–2028, for example 27 Dec 2025 against 3 Jan 2026 (C16). Read strictly, 2022 also diverges, and years outside that window diverge too (C17). Correction: Care.com moved to a calendar year during fiscal 2019, so C16 compares two rules as written, not Care.com's current calendar.	One rule describes the whole calendar	RULE_CONFLICT, 0.2; see D11
Adjustment periods	SAP: "Special periods are used to subdivide the last posting period for closing operations." (SAP Learning). Correction: the gap analysis quoted "subdivide the last posting period for closing work", which is not verbatim.	Every period covers days	Special periods, 0.2
Transition years	Business Standard (2013) reported that "as many as 226 listed companies don't follow financial years ending March", and quoted that Thomas Cook (India) "could have a 15-month period from January 2015 to March 2016" (Wayback copy). Correction: the article does not say the Companies Act, 2013 "moved" these companies; it describes a tribunal exemption. The Thomas Cook statement is conditional and calls it a period, not a year.	Years are 12 months or 52/53 weeks	exceptions.transitions, 0.2
Moving year starts	Nepal's year starts on Shrawan 1. A forum user wrote that its Gregorian date is "sometime July 16, or July 17 or July 18" (Akaunting forum). This is unverified: no authoritative source has been found. Iran's Solar Hijri calendar "is not determined by a mathematical formula" (Wikipedia); the source sentence is about leap years.	Year boundaries follow a Gregorian rule	table years, 0.2, ADR-0021, ADR-0022

The naming axis

The same dates get different labels in different organisations, so naming is configured separately from structure. A naming scheme sets year_number (start, end or majority), an offset and templates, and a calendar can have several schemes (spec/definition-v1.md).

Convention	Example and source	Status
By end year	The US federal fiscal year "begins on October 1 of each year and ends on September 30 of the following year" (31 U.S.C. 1102), so 1 Oct 2025 to 30 Sep 2026 is FY2026 under end-year naming.	Dates verified; the "FY2026" label is the proposal's
By start year	NRF names its years by start year (NRF); NRF fiscal 2023 runs from 29 Jan 2023 to 3 Feb 2024 (C04).	Verified
By start year (Japan)	The proposal says "many Japanese companies" name April 2025 to March 2026 "FY2025".	Unverified
By both years	The proposal says "FY 2025-26" or "2025/26" is common in India, the UK and Australia.	Unverified for the UK and Australia
India: FY and AY	The proposal said Indian income tax gives one April–March year two names, FY 2025-26 and AY 2026-27. Correction: these are different years. AY 2026-27 is the assessment year that follows FY 2025-26, in which that year's income is assessed. Under the Income-tax Act, 2025, which applies from 1 April 2026, "previous year" becomes "tax year", and "the use of term 'assessment year' has been discontinued" (Income Tax Department FAQ).	Corrected; see the note below
Era numbering	Sakura City publishes budget documents headed 令和8年度 (Sakura City). The mapping to April 2026 to March 2027 needs a second source.	Partly verified
Offset numbering (Thailand)	The proposal says Thai government years use the Buddhist Era (CE + 543). The 543-year difference is sourced only to Wikipedia, and no source found says Thai fiscal years are numbered this way.	Unverified
Short and aggregate forms	"FY26", "Q3 FY26", "3Q26", "P07", "H1", "9M", "YTD", "LTM" (proposal). Aggregate labels are unscheduled (PDR FR-035).	Examples only

Note on the India example. The proposal's worked India definition has an ay scheme with offset: 1 that labels the April 2025 to March 2026 year "AY 2026-27". That label names the assessment year in which the year's income is assessed under the 1961 Act; it is not a second name for the same year, and the term is discontinued for tax years from 1 April 2026. The example is illustrative, and any copy of it must say so.

What this means for the design

A fixed-date year depends only on the date. A week-based year depends on where the anchor weekday falls, so its boundaries come from a rule. Some years follow no rule and can only be listed. Everything else (quarters, periods, weeks, labels, comparisons) derives from the year boundaries plus an independent subdivision. That is why a definition has five independent blocks (ADR-0005) and fiscalclock has no presets (ADR-0004); see Definition-Format.

The existing landscape

Every version and download figure below is as of 31 Oct 2026 and links to where it was read. Corrections to the proposal and the gap analysis are in the last column.

Library or tool	Ecosystem	Covers	Notable limits	Corrections and current figures
fiscalyear	Python	Fixed-date years: year, quarter, month, day	No week-based calendars. The proposal says it uses global module state; issue #6 asks for several calendar settings in one application. Not rechecked against its source code.	Latest release 0.4.0, uploaded 17 Feb 2022, still the latest as of 31 Oct 2026 (PyPI JSON). Monthly downloads as of 31 Oct 2026: 339,074 from ecosyste.ms (a snapshot synced on 25 Aug 2026) and 206,407 for the last month from pypistats. Neither reproduces the proposal's "about 345,000".
pandas FY5253 / FY5253Quarter	Python	52/53-week years with a "nearest" or "last" variation; qtr_with_extra_week picks the quarter that gets the 14th week	Date offsets, not periods: no fiscal week or period numbers, no labels, no restatement (proposal)	None
fiscal_calendar	Python	A 4-5-4 retail date table	Requires pandas, NumPy and ReportLab (PyPI JSON, version 0.2.17 as of 31 Oct 2026)	Its description names "the 4-5-4 week schema and the 4-5-5 week schema", not one pattern
retailcalendar	Python	NRF 4-5-4 plus public holiday calendars for Brazil and the United States	4-5-4 only; GPL-3.0 licence classifier (PyPI JSON, version 1.0.0 as of 31 Oct 2026)	None
retail-calendar	JavaScript	4-4-5, 4-5-4 and 5-4-4 patterns; "nearest" and "last" rules	One year at a time. By default the last week of a 53-week year is dropped and has monthOfYear -1.	The restated option is marked "[Removed]", not deprecated, and the README says "This is no longer supported. All 53 week calendars are not restated"; no npm version carries a deprecation flag (registry). Latest 4.1.2, published 30 Oct 2024. Weekly downloads 5,252 for 23–29 Oct 2026 (npm downloads API), not "about 870".
fiscal-year-calendar	JavaScript	Claims 4-4-5, 4-5-4 and 5-4-4 patterns, country presets, holidays, QuickBooks and Xero connectors	53-week behaviour undocumented (proposal)	Latest 3.2.1, published 30 Jul 2025, as of 31 Oct 2026 (registry)
ThreeTen-Extra AccountingChronology	Java	endsOn, inLastWeekOf, nearestEndOf, withDivision, leapWeekInMonth	Java only; no labels, comparisons or bulk path (proposal)	The documents' "about 8,064 configurations" comes from the Javadoc sentence "There are approximately 7 x 2 x 12 x 4 x 12/13 x 2 = 8064 combinations." The product as written is 16,128 (taking 12) or 17,472 (taking 13), so the stated total does not match its own arithmetic. Either way the rule space is small enough to enumerate for infer.
DateTimeX::Fiscal::Fiscal5253	Perl	52/53-week years with "fiscal", "restated" and "truncated" styles	Perl only	Styles confirmed in the module documentation, read through the metacpan API because the main site showed a client challenge
Tempo / Calendrical	Elixir	Fiscal years, pattern: [4, 4, 5] retail years, year_number: :ending, academic years	Lists "Sprints and pay periods" and "Irregular academic terms" under "What is not here yet"	The proposal said academic terms are unsupported; academic years are supported, and only irregular academic terms are listed as missing
Power BI calendar-based time intelligence	DAX	Works with "Gregorian, shifted Gregorian, retail (445, 454, 544), 13-month, lunar, and more"	Needs a date table built elsewhere	A Preview feature, in a post dated 22 Sep 2025. The original URL returned 403, so the quote was checked in the Wayback copy linked here.
dbt-date	SQL / dbt	get_fiscal_periods(dates, year_end_month, week_start_day, shift_year=1) builds a fiscal period table	No documented 53-week handling	Its README notes "This package is no longer actively supported." (as of 31 Oct 2026)
SAP fiscal year variants	ERP	Posting periods, special periods, year-specific variants, shortened years	Locked inside SAP	Quotes corrected (see adjustment periods above). The source's example reads: Week-based Fiscal Year Variant ("4-4-5" fiscal year variant) for the fiscal year 2024. The gap analysis's "4-4-5 for fiscal year 2024" was not verbatim.
Rust crates	Rust	No fiscal calendar engine found	fiscal is a Brazilian NF-e document library (0.8.1 as of 31 Oct 2026, crates.io); fiscal-rs is described as a "Reserved crate name for future Fiscal related work in Rust" (crates.io)	A crates.io search for "fiscal" returns 109 crates as of 31 Oct 2026. By description, 22 are Brazilian and 3 Italian, so the documents' "mostly Brazilian tax-document and Italian tax-code libraries" is wrong. No description mentions a 52/53-week or 4-4-5 calendar engine; the nearest are quarterly, tktax-year and nepdate. fiscalclock did not exist on crates.io, PyPI or npm.

What the landscape shows

• Demand is specific. fiscalyear's issues #1, #6, #10 and #20 ask for 4-4-5 calendars, several calendars in one application, week numbers and a 29 February month end, and all four are open as of 31 Oct 2026 (issues).
• The vocabulary is shared. pandas, retail-calendar, ThreeTen-Extra and Fiscal5253 model the same settings: an end weekday, an end month, a "nearest" or "last" rule, a week pattern, and where the 53rd week goes.
• The engines exist; an open, shared one does not. Power BI and dbt consume date tables; Java and Perl have the logic but do not reach Python or JavaScript. fiscalclock's date dimension, built in 0.1.0, is the bridge.
• The claim stays narrow. The defensible description is "an open-source, data-defined engine shared across Rust, Python and JavaScript", not "no library does this": Java, Perl, Power BI, SAP and Elixir already handle parts of it.

Gap table

The proposal identifies eleven gaps. The last column shows where fiscalclock addresses each one, per the Roadmap (Proposed).

#	Gap	Evidence	Who feels it	fiscalclock release
1	One definition format for every calendar shape	Each tool models one family with its own parameter names; none expresses Vishay, broadcast or transition years (proposal)	Anyone not on a 1st-of-month year	0.1 (fixed-date and week-based); 0.2 (table, anchored, stub, exceptions)
2	Placement of the 53rd week	Apple's fiscal 2023 first quarter had 14 weeks (Apple 10-Q; cited vector apple-10q-2023-12-30.json); NRF puts it at the end of the year; Costco's Q4 grows to 17 weeks in a 53-week year (proposal); retail-calendar drops it from every month	Retail, hardware, consumer goods	0.1 (extra_week.period); 0.2 (standalone, by_year)
3	Restated and comparable views	NRF restates by "pushing each week of the 53-week year back one week, thereby ignoring the first week of the fiscal year" (NRF); for 2017 the first comparable week moves from 29 Jan–4 Feb to 5–11 Feb (C08). Fiscal5253 offers it as a query.	Anyone reporting year-on-year growth	0.3
4	Irregular and listed calendars	Transition years, Nepal and Iran year starts, SAP special periods (above)	Enterprises, governments, ERP data	0.2
5	Labels both ways	Organisations write "FY26 Q3" differently, and the libraries reviewed do not parse labels back into periods (proposal)	Reporting interfaces and APIs	0.1 (format, parse, AMBIGUOUS_LABEL)
6	Range operations	Splitting a range across periods, periods overlapping a range, period-to-date ranges	Billing, revenue recognition, dashboards	0.2
7	Cross-calendar mapping	Mapping a supplier's quarter onto yours needs hand-written overlap logic	Consolidation, partner reporting	0.3
8	Date tables for BI and warehouses	Power BI and dbt consume date tables; dbt-date documents no 53-week handling	Data engineers, analysts	0.1 (dimension, dimension_csv)
9	Columnar and bulk use	pandas offsets work element by element (proposal); Polars lists "No required dependency on pyarrow." among the benefits of its Arrow interface (Polars)	Data engineers	0.2 (ADR-0012)
10	Machine-readable contracts	The libraries reviewed ship no JSON Schema, CLI or agent tools (proposal)	Software agents, low-code tools	0.2 (schema); 0.4 (CLI, MCP, describe, infer)
11	Getting a real company's calendar	Calendars are described in 10-K prose. SEC frames can combine facts with "different reporting start and end dates" (SEC API documentation), so each filing's own period dates are the better input.	Agents, analysts covering many companies	0.4 (registry, infer)

Gaps 1 to 4 are the technical core, 5 to 9 cover everyday use, and 10 and 11 serve agents (Agents-and-MCP).