View source for Help:Type Date

{{Type
 |datatype name=Date
 |description=Holds particular points in time
 |component=Semantic MediaWiki
 |minimum version=1.4.0
 |type id=_dat
}}
The [[datatype]] '''Date''' is used for data values that represent points in time. It is able to support dates throughout human history in a unified format, and it offers internationalisation options for supporting more languages. All dates and times refer to the "local time" of the server (or the wiki). A wiki may define what timezone this refers to by common conventions. For export, times are given without timezone information. However, time offsets to that local time are supported. 

Since {{Release|1.8.0}} dates are stored in a fully serialised format, including the calendar model.

== Display format ==

Dates are displayed in a simple format that cannot be changed with the language setting in the user preferences. Month names in displayed dates are just translated based on the wiki's current language (if translated names are available). User settings are not taken into account for displaying dates.

Display takes into account if parts of a date were omitted. So a date specified as "2008" will also be printed as "2008" everywhere, even though it might be interpreted as "Jan 1 2008 00:00:00" when comparing it to other dates.

== Result formatters ==

=== <code>#ISO</code> ===
In case you want to keep the simple format in printout request of queries ([[Help:Inline queries|Inline queries]] or [[Help:Concepts|Concepts]]) you may use "<code>ISO</code>" behind the printout requests of this type. Thus instead of displaying "Jan 9 2008" (achieved with printout request <code>?birthday</code>) you will get "2008-01-09" (achieved with printout request <code>?birthday#ISO</code>) which is a plain format representing an ISO formatted international date string.

=== <code>#ISO-P</code> ===
Unlike the "<code>ISO</code>" result formatter which completes partial dates, the "<code>ISO-P</code>" (P for "partial") formatter renders partial dates in ISO formatting:
* 2022 → 2022
* April 2022 → 2022-04
* 1 April 2022 → 2022-04-01
Rationale: Sometimes, only a year or a year and month are specified for a date, e.g. during planning of events. At a later point in time, the date is completed with a month and day.

This formatter is available starting with {{Release|4.1.0}}.

=== <code>#MEDIAWIKI</code> ===
Starting with {{Release|1.7.0}} you can also use "<code>MEDIAWIKI</code>" behind the printout request to use the MediaWiki's i18n methods for time and date formatting. It has superior i18n support, but cannot handle all possible values such as BC dates.

To correspond with the MediaWiki output, "<code>MEDIAWIKI</code>" will recognize the user settings in terms of preference and language settings.

=== <code>#LOCL</code> === 
Starting with {{Release|2.4.0}}[[CiteRef::gh:smw:1545]] it is also possible to display values in a per language predefined format for a total of four precisions:
# <code>Y</code> (year)
# <code>F Y</code> (year, month)
# <code>F j, Y</code> (year, month, day)
# <code>H:i:s, j F Y</code> (year, month, day, hour, minute, second)
# <code>TO</code> in local time set in users preferences  (see [[Local_time]].)
# <code>@de-at</code> in local time for a specific language (here Austrian German)

The predefined format will be shown to the user according to his or her preference setting for language (user language). It will always be used when browsing data via special page [[Help:Special:Browse|"Browse"]] or for the annotated data values shown on a property page of type "Date". The shown precision depends on the data value annotated to the respective property: If a date without timestamp information is annotated like e.g. <code><nowiki>[[Has date::2016/08/17]]</nowiki></code> the browsing interfaces and queries will automatically select the "<code>F j, Y</code>" precision to format it for display: "August 16, 2016" (English), etc.

When the local time of the user differs from the server time, local time can be used. See [[Local_time]].

{{Callout
 |If a precision was not specified for a language the default formatting for English will apply.
 |info
}}

; Examples
See the help page on [http://sandbox.semantic-mediawiki.org/wiki/Issue/1545_(LOCL) <sandbox.semantic-mediawiki.org>] for a live example.

=== <code>#F</code> (free formatted) ===
Starting with {{Release|2.4.0}} [[CiteRef::gh:smw:1389]], the free format is supported where a options string in form of <code>D M j G:i:s T Y</code> (see [http://php.net/manual/en/function.date.php <code>DateTime</code>]) can be used to generate an individual printout. Limitations: 

* Dates like 10000 BC (prehistoric) are not supported by the formatter (the ISO date --10000-01-01 is returned instead) other BC(E) dates like 2 Feb 900 BC will be formatted as -0900/01/25 or -0900/02/02 JL.
* Dates stored with a JD(JL) are not automatically transformed and instead marked with JL to indicate its model

<pre>
{{#ask:
 [[Example]]
 |?Date#GR-F[Y/m/d H:i:s]=Label 1 (GR)
 |?Date#-F[Y/m/d H:i:s]=Label 2
 |?Date#-F[D M j G:i:s T Y]=Label 3
 |?Date#-F[l jS \of F Y h:i:s A]=Label 4
}}
</pre>

=== <code>#SORTKEY</code> ===
Return a number that helps comparing time data items. For dates in the Julian Day era (roughly from 4713 BCE onwards) its is equivalent to the the Julian Day number. For earlier dates, the (negative) year number with a fraction for the date is used (times are ignored).

=== <code>#JD</code> ===
Returns the [[wp:Julian day|Julian day]] of a date value.

== Input examples ==
; Examples of typical input dates in English language are:
{| class="smwtable-clean"
|-
|'''annotation'''||'''result'''||'''remark'''
|-
| <tt><nowiki>[[Has date::Feb 11 2000 10:00:01]]</nowiki></tt> || [[Has date::Feb 11 2000 10:00:01]] || complete date with time
|-
| <tt><nowiki>[[Has date::Feb 11 2000]]</nowiki></tt> || [[Has date::Feb 11 2000]] || just date
|-
| <tt><nowiki>[[Has date::Feb 2000]]</nowiki></tt> || [[Has date::Feb 2000]] || month and year
|-
| <tt><nowiki>[[Has date::2000]]</nowiki></tt> || [[Has date::2000]] || year by itself
|-
| <tt><nowiki>[[Has date::Feb 11 2000 10:00:01 PM]]</nowiki></tt> || [[Has date::Feb 11 2000 10:00:01 PM]] || complete date with time, PM
|-
| <tt><nowiki>[[Has date::Feb 11 2000 22:00:01]]</nowiki></tt> || [[Has date::Feb 11 2000 22:00:01]] || complete date with 24h time
|-
| <tt><nowiki>[[Has date::2000-02-11T22:00:01]]</nowiki></tt> || [[Has date::2000-02-11T22:00:01]] || ISO-style date
|-
| <tt><nowiki>[[Has date::2000-02-11T22:00:01+02:00]]</nowiki></tt> || [[Has date::2000-02-11T22:00:01+02:00]] || ISO-style date with offset
|-
| <tt><nowiki>[[Has date::2000 February 2]]</nowiki></tt> || [[Has date::2000 February 2]] || varying order of inputs is supported
|-
| <tt><nowiki>[[Has date::2-3-2000]]</nowiki></tt> || [[Has date::2-3-2000]] || preferred interpretation, month or day, sometimes depends on language settings
|-
| <tt><nowiki>[[Has date::2/3/2000]]</nowiki></tt> || [[Has date::2/3/2000]] || various kinds of separators are recognized in all languages
|-
| <tt><nowiki>[[Has date::Jan 1 300 BC]]</nowiki></tt> || [[Has date::Jan 1 300 BC]] || dates BC/before common era are supported
|-
| <tt><nowiki>[[Has date::14000000000 BC]]</nowiki></tt> || [[Has date::14000000000 BC]] || estimated age of the universe
|-
| <tt><nowiki>[[Has date::Feb 11 2000 Jl]]</nowiki></tt> || [[Has date::Feb 11 2000 Jl]] || date of the Julian Calendar
|-
| <tt><nowiki>[[Has date::Feb 11 1492 Gr]]</nowiki></tt> || [[Has date::Feb 11 1492 Gr]] || date is treated as Gregorian
|-
| <tt><nowiki>[[Has date::Feb 11 2000 10:00 GMT]]</nowiki></tt> || [[Has date::Feb 11 2000 10:00 GMT]] || date with time zone shortcut
|-
| <tt><nowiki>[[Has date::2000-02-22]]</nowiki></tt> || [[Has date::2000-02-22]] || MySQL date format
|-
| <tt><nowiki>[[Has date::Sun Jun 20 23:21:05 +0200]]</nowiki></tt> || [[Has date::Sun Jun 20 23:21:05 +0200]] || per se an incorrect ISO date {{Note|Starting with {{Release|3.2.0}} this annotation format will be recognized.[[CiteRef::gh:smw:4692]]}}
|}

; The annotation in the following examples is incorrect:
{| class="smwtable-clean"
|-
|'''wrong annotation'''||'''result'''||'''remark'''
|-
| <tt><nowiki>[[Has date::1999-00-00]]</nowiki></tt> || [[Has date::1999-00-00]] || MySQL partial date format
|-
| <tt><nowiki>[[Has date::Sun Jun 20 23:21:05  1993]]</nowiki></tt> || [[Has date::Sun Jun 20 23:21:05  1993]] || unrecognized order
|}
Other languages may also support additional strings as month names, and they may choose different preferred interpretations of ambiguous dates. The basic format, however, is the same.

=== Further examples ===
* [http://sandbox.semantic-mediawiki.org/wiki/Partial_dates sandbox.semantic-mediawiki.org - partial dates examples]
* [http://sandbox.semantic-mediawiki.org/wiki/Issue/1397_%28Microseconds%29 Microseconds] [[CiteRef::gh:smw:1397]]
* [http://sandbox.semantic-mediawiki.org/wiki/Issue/1389_%28DateFreeFormat%29 Free formatted]
* [http://sandbox.semantic-mediawiki.org/wiki/Issue/1533 1533] shows output on different format options in context of an explicit page content language
{{API example}}

== Calendar models ==
At the moment, Type:Date supports two calendar models: Gregorian and Julian
In 1582 the Catholic Church introduced a reform of the calendar Julian calendar. So dates before 24. February 1582 are supposed to refer to Julian calendar by default. The dates after the reform are considered Gregorian accordingly. However, one can manually specify the calendar model of the entered date by annotating it with Jl or Gr (Old Style (OS) is also understood).
Internally, Type:Date uses the [[wikipedia:proleptic Gregorian calendar|proleptic Gregorian calendar]], an extension of the Greogorian calendar to the past, to represent dates.

{{Release|1.8.0}} added support for new output formats "<code>GR</code>" and "<code>JL</code>" that can be used in [[Help:Inline queries|inline queries]] to define the desired calendar model that should be displayed. The same strings also work as modifiers when writing dates. If nothing is given, SMW will assume the same default calendar model on input and on output.

Instead of displaying the annotated date „6 November 1796 Jl“ with the output statement <code>?Geburtsdatum</code>, one may have this date displayed as „17 November 1796 Gr“ by using the output statement <code>?Geburtsdatum#GR</code>.

{{Release|2.4.0}} is to indicate the calendar model for a date if is not a Greogorian calendar date and <code>SMW_DV_TIMEV_CM</code>[[CiteRef::gh:smw:1545]] can be used to disable this [[Help:$smwgDVFeatures|option]].

== Maximal date range ==
Type:Date is able to handle dates across history with full precision for storing, and substantial precision for sorting and querying. The range of supported past dates should encompass the Beginning of Time according to most of today's theories. The range of supported future dates is limited more strictly, but it does also allow year numbers in the order of 10^9.

== Era information ==

Display of era information for positive years (if denoted) is supported starting with {{Release|2.4.0}}.[[CiteRef::gh:smw:1396]]

=== BC, negative years, and the year 0 ===
Years before common era (aka BC) can be denoted using "BC" in a date. It is assumed that there is no "year 0": the historic sequence of years was ..., 2 BC, 1 BC, 1 AD, 2AD, ... When given as an input, the year 0 (BC or not) is interpreted as 1 BC, but this use is discouraged.

The internal numeric date model used in SMW supports the year 0, and considers it to be the same as "1 BC". According to this convention, e.g., the year "-100" is the same as "101 BC". This convention agrees with ISO 6801 and the remarks in XML Schema Datatypes 2nd Edition (the latter uses a different convention that disallows year 0, but it explicitly endorses the ISO convention and announces the future use of this in XML). Note that the implementation currently does not support the specification of negative year numbers as input; negative numbers are only used internally.

== Time offsets and timezones ==
Time offests are supported (e.g. "1 1 2008 12:00-2:00"). As explained above, those refer to the local time. Time offsets take leap years into account, e.g. the date "Feb 28 2004 23:00+2:00" is equivalent to "29 February 2004 01:00:00", while "Feb 28 1900 23:00+2:00" is equivalent to "1 March 1900 01:00:00". Additionally, offsets can be specified by the common shortcuts for time zones (e.g. ADT, AST, CET, CST, CXT, EST, HAC, HAT, HNR, MEZ, MST, NFT): "1 March 1998 08:00:00 EST".

== Sorting dates in tabular outputs ==
The sortable table code of [[MediaWiki]] cannot handle dates. To make them sort properly, one needs to provide numeric sortkeys using the "data-sort-value" attribute in td elements (look at the HTML of any real SMW table for examples). To allow this to be done, the  new parameter "<code>#SORTKEY</code>" was added to this datatype by which one can obtain a numeric sortkey as needed for "data-sort-value". For example, the following query displays dates and their sortkeys:

<pre>
{{#ask:
 [[Modification date::+]]
 |?Modification date
 |?Modification date#SORTKEY
}}
</pre>

For properties that can have many values, only one "<code>#SORTKEY</code>" must be used (since the whole table row is sorted as one, even if many dates are in one cell). This can be achieved by using parameter "<code>+limit</code>" like in this example:
<pre>
{{#ask:
 [[Testdate::+]]
 |?Testdate
 |?Testdate#SORTKEY |+limit=1
}}
</pre>

== Handling of incomplete dates ==
The implementation notices and stores whether parts of a date/time have been omitted (as in "2008" or "May 2007"). For all exporting and sorting purposes, incomplete dates are completed with defaults (usually using the earliest possible time, i.e. interpreting "2008" as "Jan 1 2008 00:00:00"). But the information on what was unspecified is kept internally for improving behaviour e.g. for outputs (defaults are not printed when querying for a value). 

Only the minor parts of a date can be omitted: "May 2008" works, but "May 1" does not. This is so, since the latter could not be given a sensible default interpretation when sorting dates. To support sorting and querying, all dates must be interpretable as a concrete precise time point, and this is done internally when required, even for incomplete dates.

== Technical notes ==
See [[CiteRef::gh:smw:1545]]
* <code>TimeValueFormatter::getCaptionFromDataItem</code> uses the content language which is either the default [[content language]] or if available the [[page content language]]
* <code>ExtraneousLanguage::getPreferredDateFormatByPrecision</code> determines a PHP DateTime format string as preference for a specific language in combination with a precision
* <code>IntlTimeFormatter::getLocalizedFormat</code> (#LOCL) uses <code>ExtraneousLanguage::getPreferredDateFormatByPrecision</code> to determine the preferred localized representation for a date/time output

== Open Issues ==
* SMW does not yet offer full support for dates of 10,000 BC and earlier.{{SMWIssue|5153}}[[CiteRef::gh:smw:5153]]
* The customised date formatting of MediaWiki can only be used for dates between typically between 1901-12-14 and 2038-01-19.
* Internationalisation is incomplete: "BC", "AD", "PM", "AM" are fixed for all languages.
* Conversion between (historic) calendar models is not supported yet.

<div style="display: none">
{{DEFAULTSORTKEY:Date}}
{{#scite:gh:smw:1389
 |type=pullrequest
 |url=https://github.com/SemanticMediaWiki/SemanticMediaWiki/pull/1389
}}
{{#scite:gh:smw:1397
 |type=pullrequest
 |url=https://github.com/SemanticMediaWiki/SemanticMediaWiki/pull/1397
}}
{{#scite:gh:smw:1396
 |type=pullrequest
 |url=https://github.com/SemanticMediaWiki/SemanticMediaWiki/pull/1396
}}
{{#scite:gh:smw:1545
 |type=pullrequest
 |url=https://github.com/SemanticMediaWiki/SemanticMediaWiki/pull/1545
}}
{{#scite:gh:smw:4692
 |type=pullrequest
 |url=https://github.com/SemanticMediaWiki/SemanticMediaWiki/pull/4692
}}
{{#scite:gh:smw:5153
 |type=issue
 |url=https://github.com/SemanticMediaWiki/SemanticMediaWiki/issues/5153
}}
{{doc.info
 |master page=Help:Type_Date
 |status=effective
 |progress=100
 |priority=2
 |minversion=3.2.0
}}
</div>