MeridianMERIDIAN

Year-Month (ISO truncated)

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.

Worked samples

DuckDB 1.5.5 · finetype 0.6.64

ValueAs DATEmonthyear
2024-012024-01-0112024
2023-122023-12-01122023
2000-062000-06-0162000
%Y
four-digit year
%m
month, two digits

Shape

Pattern
^\d{4}-\d{2}$
ValueLengthShape
2024-017matches
2023-127matches
2000-067matches
2024-06rejected: one character short

Background

Origin

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

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

XML Schema 1.1 defines a datatype, gYearMonth, that represents specific whole Gregorian months in specific Gregorian years.[3] The lexical form of XML Schema's gYearMonth is a year, a hyphen and a month, optionally followed by a timezone.[3] The Frictionless Table Schema defines a yearmonth field type as a specific month in a specific year as per XMLSchema gYearMonth.[4] The Frictionless Table Schema gives YYYY-MM as the usual lexical representation of yearmonth, with no format options.[4]

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] The ECMAScript Date Time String Format includes YYYY-MM among its date-only forms.[6] When the DD element is absent from an ECMAScript date string, 01 is used in its place.[6] ECMAScript interprets date-only forms without a UTC offset as a UTC time.[6]

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] 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]

Sources

  1. [1]ISO 8601secondary source
  2. [2]Date and Time Formatsstandard
  3. [3]W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypesstandard
  4. [4]Table Schema | Data Package (v1)standard
  5. [5]datetime — Basic date and time types — Python 3.15.0 documentationdocumentation
  6. [6]ECMAScript® 2027 Language Specificationstandard
  7. [7]prc_hicp_manrdataset
  8. [8]EXRdataset

Detection notes

New in format coverage expansion. ISO 8601 truncated date. Transform appends -01 to create full date for strptime.

Use it

CLI · DuckDB
$ finetype infer -i "2024-01" --mode column
→ datetime.date.year_month

SELECT ft_infer('2024-01');
-- → 'datetime.date.year_month'
Cast expression
strptime({col} || '-01', '%Y-%m-%d')::DATE
-- Format: %Y-%m

Schema

https://meridian.online/schemas/datetime.date.year_month · Frictionless type yearmonth

finetype taxonomy datetime.date.year_month -o json-schema

Aliases

yearmonth

Type Registry