Concepts
Week numbers, and why the calendar's are the wrong ones
Every institution numbers its teaching weeks, almost none of them number them the way the calendar does, and the gap is where a surprising amount of confusion lives.
Two different numbers with the same name
Ask the calendar what week it is and you get the ISO week number: week 1 is the week containing the first Thursday of January, and by the start of a northern-hemisphere academic year you are somewhere around week 36 to week 40.
Ask a timetabling office the same question and you get a completely different number. Week 1 is the first teaching week of the year, wherever in the calendar it happens to fall, and everything is counted from there. It is the number printed on the timetable, the number in the room-booking form, and the number two colleagues use when they arrange to meet in week 9.
The two are never the same unless an institution's teaching year happens to start in the first week of January, which is to say: never. And because both are called the week number, software that quietly produces the wrong one produces something that looks entirely plausible.
What it looks like when it goes wrong
It does not look like an error. It looks like a page with a number at the top of it, and the number is wrong by a different amount at every institution — because each one starts its year on a different date.
That is what makes it expensive. A crash is reported in an hour. A heading that reads Week 36 when everybody in the building calls it Week 2 is reported weeks later, by somebody who assumed they had misunderstood the system rather than that the system had misunderstood them — and in between, people have been turning up to rooms on the strength of it.
The rule that avoids it is short: a week number is read, never computed. The institution decides where week 1 is; software's job is to report what the institution decided, not to derive a number of its own from a date.
Week 1 is not always the first week that exists
Institutions routinely need dates before their teaching year: an induction fortnight, a resit period, a summer school that belongs to the year just ending. Rather than renumber everything — which would silently change the meaning of every timetable, every booking and every message anybody has ever sent about week 9 — the sensible move is to extend the calendar backwards, into zero and into negative numbers.
It reads oddly the first time and it is exactly right the second: week 1 keeps meaning what it has always meant, and the fortnight before it is week −1 and week −2. We have institutions whose week table runs a long way into the negative and a long way past the end of the teaching year, and everything in between addresses a real date.
Anything reading a timetable programmatically should expect that. A week number is a signed integer, not a counter that starts at one.
And some institutions do not use numbers at all
Oxford and Cambridge name their weeks by term rather than counting them across the year: a date is in Michaelmas fourth week, and a number would mean nothing to anybody in the room. Other institutions label a fortnight as Revision, Induction or Assessment period and expect the timetable to say so.
So a teaching week carries two things, not one: the number the software addresses it by, and the institution's own name for it, which is what a reader actually wants at the top of the page. Where a name exists it should be printed instead of the number and printed in full — abbreviating somebody's term convention to save eight pixels is the kind of helpfulness nobody asked for.
Where no name exists, and for most institutions none does, the number is the name and that is perfectly fine.
Four things worth checking in any timetabling system
None of them is exotic. All of them are quietly wrong somewhere.
| Question | What a good answer looks like |
|---|---|
| Where does week 1 start? | A date your institution set, stored once, used everywhere. Not derived from the calendar and not configurable per screen. |
| Can the calendar go before week 1? | Yes, into zero and negative numbers, without renumbering anything that already exists. |
| Can a week carry a name? | Yes, and the name is printed instead of the number, in full. |
| Where does a student app get the number? | From the timetable, in the same answer as the lessons. A client that computes its own will be wrong, and wrong differently at every institution. |
Why this is an integration question too
A portal, an app or an information screen that shows a week heading has to get this from somewhere, and the only source that can be right is the timetable itself. In Wise Timetable the schedule answer carries the week numbers and week names for the range it covers, so a client never has a reason to work one out — and GET /v2/weeks answers the same question on its own for a screen that needs to label a whole term at once.
The REST API manual documents both, including the negative case, and it is published in full and ungated so a developer can check the shape of the answer before anybody signs anything.
Want to see this working?
Book a 45-minute online presentation and we will walk through it against your institution's own scheduling problem.