Proposal:Date namespace

From OpenStreetMap Wiki
(Redirected from Date namespace)
Jump to navigation Jump to search
Date namespace
Proposal status: Draft (under way)
Proposed by: RicoZ
Draft started: 2014-12-19

The date namespace is a suffix of a key specifying information about time periods of validity for the suffixed key. In Openstreetmap it is particularly frequently used with name=* and variations of it. It is completely and utterly unrelated to the history/changeset function of the OSM database.

When only ranges of years are specified (no month or other details) a single hyphen may be used, such as "name:1953-1990 = Ernst-Thälmann-Straße".

When full dates are specified or the simple notation is not sufficient a subset of the ISO 8601 date format can be used with a double hyphen ("--") as date range separator - eg "amenity:1965--1971-12-18 = school".

It should be considered that historical objects of which there are no visible traces left normally do not belong into the main OSM database. Several initiatives exist to build historical maps with own databases. As an exception apparently many mappers think extensive history of object names is worth recording in main database.

Mapping things like "narrow gauge railway existed here in years 1835-1870 and now is completely gone without any trace whatsoever" is out of scope for OpenStreetMap, but OHM is a separate project where such mapping is welcomed.

Note that mapping features that are gone but left some kind of traces is accepted, there is no agreement what kind of traces is necessary. See for example demolished railway for more detail.

How to map

Add the suffix specifying a year or date range to the main key or other relevant tags. The suffix is not needed for attributes which did not change over time.

key:date-date = value
key:date--date = value
key:date- = value
key:-date = value

Each key should be in long ISO 8601 format (YYYY, YYYY-MM, or YYYY-MM-DD) with fixed number of digits for their components (left-padded with zeroes), and recommended separation of components with single hyphen. A yearly or monthly recurrent partial date, omitting the leading year (MM-DD, or MM), may also be used (but such date is not in standard ISO 8601 format which requires the leading year) then separated with double hyphens.

A single hyphen - is sufficient to separate dates in date ranges when both dates are in ISO 8601 format and specify the required leading year (with 4 digits); double hyphens -- are required be used when date ranges are specified using recurrent dates with omitted years. Months and days of months should always use a two-digit format (with leading zero where needed).

So the values can have one the following formats:

  • YYYY-MM-DD, YYYY-MM, or YYYY (only for the non-recurring specified date: a full day, a full month, or a full year)
  • YYYY-MM-DD-, YYYY-MM-, or YYYY- (open-ended interval since start of the specified date)
  • -YYYY-MM-DD, -YYYY-MM, or -YYYY (open-ended interval until end of the specified date)
  • YYYY-MM-DD-YYYY-MM-DD, YYYY-MM-YYYY-MM, or YYYY-YYYY (interval between start of first date and end of the second date: recommanded variant)
  • YYYY-MM-DD--YYYY-MM-DD, YYYY-MM--YYYY-MM, or YYYY--YYYY (interval between start of first date and end of the second date: obsolete variant)
  • MM-DD or MM (only for the specified interval recurring every year: a full day or a full month). For example, 01-02 means only February the 1st every year, not from January to February every year.
  • MM-DD- or MM- (only for the specified interval recurring every year, since start of the specified day or month in the year until the end of the same year)
  • -MM-DD or -MM (only for the specified interval recurring every year, since start of the year until end of the specified day or month in the same year)
  • MM-DD--MM-DD or MM--MM (only for the specified interval recurring every year: a full day of the yeat or a full month or the year; separation with double hyphens is required)


  • 2017-01-01-2017-12-31, 2017-01-2017-12, or 2017-2017 should not be used, but they are equivalent to just 2017: preferably use the shortest notation.
  • 02-15--02-30 is valid every year, but it would be equivalent to 02-15- (if the a month does not have at least the specified number of days, the value is interpreted as until end of that month).
  • 01-01--12-31, 01--12, 01-01-, 01-, -12-31, -12 are all equivalent and should not be used: it would always match all possible dates.
  • It's still not possible to specify a specific day of the month (or a specific range of days of the month) recurring every month: a possible alternative would be to use a special invalid month number like 00 (for example, -00-15 would mean the first half of every month, and 00-16- would mean the second half of every month; and 00-01--00-31, 00-01-, -00-31 are equivalent and should not be used as it would match all days of every month).
  • ISO 8601 allows specifying dates with ISO week numbers and ISO year numbering (such as 2017-W01 meaning the first full week of the year from Monday to Sunday, possibly including up to 3 days in the previous year, and 2017-W01-1-2017-W01-5 would be the working days of the same week from Monday to Friday); these formats is still not supported (as well 2017-Q1 for the first quarter of 2017 is not supported: use 2017-01-2017-03 instead).

Fallback for current state:

key = value

Add a fallback variant without the date namespace for the current state. Even if one of the date ranges already includes "up until now" many data consumers will not deduce this information.

The date namespace suffix can also be combined with a lifecycle prefix although not all combinations make sense.

Advantages and Disadvantages

List should be kept identical with that in

Main article: Comparison of life cycle concepts

See talk page for currently ongoing discussion of problems.


  • Will not confuse existing applications.
  • Allows complete history record with per-tag distinctions.
  • Can be combined with other tags.
  • Can be combined with "status:tag" style life cycle tagging.
  • Supports adding historical/future information to currently used features if desired.


  • Difficult to search for objects by year (range) or objects using this tagging scheme.
  • Duplication when current and past use overlap (eg building:1930-=house + building=house ought to be used).
  • Datespec needs to be added to most tags separately where it applies to several tags. This does increase flexibility but also means some data duplication and more work when editing.
  • For a single object with various tags affixed with dateranges it is difficult to ascertain whether equal dateranges refer to exactly identical periods of time or just happen to be identical strings which might have been slightly differing time periods in reality but resulted in identical daterange strings because of lack of precision or missing exact dates.


To map a school that became disused and was then converted into a house with the complete history
  • building = house
  • building:1971-12-18-- = house
  • amenity:1835-1965 = school
  • amenity:1965--1971-12-18 = school
  • name = The Old School
  • name:1835-1965 = St Cakes Primary School
  • name:1971-12-18-- = The Old School
A highway with a long history, changes in name, classification, reference and surface etc
  • highway = pedestrian
  • highway:1932-1974 = primary
  • highway:1974- = pedestrian
  • maxspeed = 30
  • maxspeed:1957--1992-05 = 50
  • maxspeed:1992-05-- = 30
  • name = Konrad-Adenauer-Straße
  • name:1871-1933 = Kaiserstraße
  • name:1933-1945 = Adolf-Hitler-Straße
  • name:1945-1953 = Stalinstraße
  • name:1953-1990 = Ernst-Thälmann-Straße
  • name:1990- = Konrad-Adenauer-Straße
  • ref = B 96
  • ref:1932-1960 = R 96
  • ref:1960-1990 = F 96
  • ref:1990- = B 96
  • surface = paved
  • surface:1890-1927 = cobblestone
  • surface:1927- = paved

Other variants

The OSM database has many entries like historic:DATERANGE:key or his:DATERANGE:key

See also