Date specification
OpenStreetMap uses a subset of the ISO 8601 standard for single dates, and in most cases a simplified (not ISO 8601 compatible) notation for year ranges.
Single date
In the simplest case the date is a four digit year ("YYYY") or full date as ("YYYY-MM-DD")
Examples:
- "1984"
- "1984-03-27"
Date ranges
In most cases the format "YYYY-YYYY" (such as "1964-1986") is used and allows only the specification years.
To avoid parsing ambiguities and allow easier filtering of tags, please use unabbreviated formats, with fixed number of digits, i.e. with leading zeroes if necessary for day and month numbers, and use hyphens between each date component.
If a range defined by full dates should be specified, a double hyphen ("--") could be used as date separator - eg "1964-01-28--1986-03-17" or "1965--1986-03-17". However this is not necessary when the ending date starts by a year on 4 digits (so "1964-01-28-1986-03-17" is also valid and unambiguous), or when the starting and ending date are missing (in which case a single hyphen starting or ending the value means a data range).
Examples:
- "-1964" - until 1964, alternative and rarely used form "--1964"
- "1964-" - from 1964 and still valid, alternative and rarely used form "1964--"
- "1964-1986" - years 1964-1986, alternative form "1964--1986"
- "1964-01-28-1986-03-17" - alternative form "1964-01-28--1986-03-17"
- "1965-1986-03-17" - alternative form "1965--1986-03-17"
The double hyphen may be necessary only for date ranges omitting years (but those dates are not in ISO 8601 format, which requires the leading 4-digit year). (Note that ISO 8601 use a slash "/" for the separator in date ranges, but still requires the year; older versions of ISO 8601 also allowed partial dates without year but used "--" to replace the omitted year).
Examples:
- "01--03" - from start of January to end of March (in any year)
- "01-03" - 3 January only (in any year)
- "01-01--01-15" - from 01 January to 15 January (in any year)
"01-01-01-15"- ambiguous parsing, don't use.
Uses in Openstreetmap
Date namespace
The date namespace can be used to map history of features.
- example "building:1910--1955=school" + "building:1955--=house" (rarely used form with double hyphen, that conflicts with older version of ISO 8601)
- example "building:1910-1955=school" + "building:1955-=house" (most common form using single hyphen)
Key:opening_date
See opening_date=*
Software considerations
In places where single dates are expected normal ISO 8601 parsing routines should yield correct results.
In places where date ranges are expected the software could check for the simplified single hyphen notation and then fall back to ISO 8601 parsing of date ranges.