ISO Week Number

Converts between calendar dates and ISO 8601 week numbers, in either direction, and reports how many weeks an ISO year has. Use this whenever a date needs to be expressed as a week number, or a week number needs to be turned back into a date — sprint planning, report periods, "week 37" style scheduling, or reconciling two systems that disagree about what week it is. DO NOT compute this yourself with day-of-year divided by 7. ISO 8601 week 1 is defined as the week (Monday-Sunday) containing the year's first Thursday, not the week containing January 1st. This has two consequences that are easy to get wrong from memory: late-December dates can belong to ISO week 1 of the NEXT calendar year, and early-January dates can belong to ISO week 52 or 53 of the PREVIOUS calendar year. A year has 53 ISO weeks (not the usual 52) exactly when January 1 is a Thursday, or the year is a leap year and January 1 is a Wednesday — a rule nobody carries around, and getting it wrong produces a plausible-looking but incorrect week number with no visible sign of the error. Input is a single string, and the shape of the string picks the operation: "2027-01-01" a calendar date (YYYY-MM-DD) -> returns its ISO year, week, and weekday "2026-W53" an ISO week, no weekday given -> returns the Monday of that week "2026-W53-5" an ISO week and weekday (1-7, Mon-Sun) -> returns that exact date "2026" a bare 4-digit year -> returns whether it has 52 or 53 ISO weeks Refuses rather than guesses: slash-separated dates like "03/04/2025" are rejected as ambiguous (month/day vs day/month), two-digit years are rejected as a guess, invalid calendar dates (Feb 30) are rejected, and a week number beyond what that ISO year actually has (e.g. week 53 of a 52-week year) is rejected and told how many weeks that year has.

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['input'], 'properties': {'input': {'type': 'string', 'description': 'A calendar date "YYYY-MM-DD" (e.g. "2027-01-01"), an ISO week "YYYY-Www" or "YYYY-Www-D" where D is 1-7 for Monday-Sunday (e.g. "2026-W53-5"), or a bare 4-digit year (e.g. "2026") to ask how many ISO weeks it has.'}}}