# Year-Month (ISO truncated)

Key: `datetime.date.year_month`

ISO 8601 truncated form with no day component. Pervasive in monthly time-series data, financial reporting, and API responses. Transforms to first day of month.

Page: <https://meridian.online/docs/projects/finetype/types/datetime/date/year_month>

Format: `%Y-%m`

Samples: `2024-01`, `2023-12`, `2000-06`

## Background

### Origin

ISO 8601 was first published as ISO 8601:1988 in June 1988.[[1]](https://en.wikipedia.org/wiki/ISO_8601) ISO 8601 allows calendar dates to be written with reduced precision, such as 1981-04 for April 1981.[[1]](https://en.wikipedia.org/wiki/ISO_8601) When the day is left out of an ISO 8601 calendar date, only the YYYY-MM form is allowed.[[1]](https://en.wikipedia.org/wiki/ISO_8601)

The W3C note Date and Time Formats, by Misha Wolf and Charles Wicksteed, was submitted to W3C on 15 September 1997.[[2]](https://www.w3.org/TR/NOTE-datetime) The W3C note lists Year and month as one of its permitted levels of precision, written YYYY-MM, for example 1997-07.[[2]](https://www.w3.org/TR/NOTE-datetime) The W3C note restricts ISO 8601 to a small number of formats to reduce the scope for error and the complexity of software.[[2]](https://www.w3.org/TR/NOTE-datetime)

XML Schema 1.1 defines a datatype, gYearMonth, that represents specific whole Gregorian months in specific Gregorian years.[[3]](https://www.w3.org/TR/xmlschema11-2/) The lexical form of XML Schema's gYearMonth is a year, a hyphen and a month, optionally followed by a timezone.[[3]](https://www.w3.org/TR/xmlschema11-2/) The Frictionless Table Schema defines a yearmonth field type as a specific month in a specific year as per XMLSchema gYearMonth.[[4]](https://specs.frictionlessdata.io/table-schema/) The Frictionless Table Schema gives YYYY-MM as the usual lexical representation of yearmonth, with no format options.[[4]](https://specs.frictionlessdata.io/table-schema/)

### Use

A year-month value names a whole month, not a day, so the analyst's first decision is whether a column of them should become a date at all. (Meridian's view) Padding each value to the first of the month makes it sortable and joinable as a date, but the day it gains is invented and should not be read as an event date. (Meridian's view) Keeping the value as text, or splitting it into integer year and month columns, is often the more honest choice for monthly statistics. (Meridian's view)

Python's date.fromisoformat does not currently support reduced precision dates such as YYYY-MM.[[5]](https://docs.python.org/3/library/datetime.html) The ECMAScript Date Time String Format includes YYYY-MM among its date-only forms.[[6]](https://tc39.es/ecma262/multipage/numbers-and-dates.html) When the DD element is absent from an ECMAScript date string, 01 is used in its place.[[6]](https://tc39.es/ecma262/multipage/numbers-and-dates.html) ECMAScript interprets date-only forms without a UTC offset as a UTC time.[[6]](https://tc39.es/ecma262/multipage/numbers-and-dates.html)

### Where you'll meet it

Eurostat's SDMX-CSV extract of the prc\_hicp\_manr dataset for the euro area writes its monthly TIME\_PERIOD values as 2024-01, 2024-02 and 2024-03.[[7]](https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/prc_hicp_manr/M.RCH_A.CP00.EA?format=SDMX-CSV&startPeriod=2024-01&endPeriod=2024-03) The European Central Bank's data API writes the monthly US dollar/euro reference rate's TIME\_PERIOD values as 2024-01, 2024-02 and 2024-03.[[8]](https://data-api.ecb.europa.eu/service/data/EXR/M.USD.EUR.SP00.A?format=csvdata&startPeriod=2024-01&endPeriod=2024-03)

## Sources

1. [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) — secondary source
2. [Date and Time Formats](https://www.w3.org/TR/NOTE-datetime) — standard
3. [W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes](https://www.w3.org/TR/xmlschema11-2/) — standard
4. [Table Schema \| Data Package (v1)](https://specs.frictionlessdata.io/table-schema/) — standard
5. [datetime — Basic date and time types — Python 3.15.0 documentation](https://docs.python.org/3/library/datetime.html) — documentation
6. [ECMAScript® 2027 Language Specification](https://tc39.es/ecma262/multipage/numbers-and-dates.html) — standard
7. [prc\_hicp\_manr](https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/prc_hicp_manr/M.RCH_A.CP00.EA?format=SDMX-CSV&startPeriod=2024-01&endPeriod=2024-03) — dataset
8. [EXR](https://data-api.ecb.europa.eu/service/data/EXR/M.USD.EUR.SP00.A?format=csvdata&startPeriod=2024-01&endPeriod=2024-03) — dataset